# Import an existing AWS RDS instance

> Using your pre-existing database instead of provisioning a new one


# Overview

When deploying applications to your own cloud, Encore Cloud can provision all necessary infrastructure—including database instances. However, if you already have an AWS RDS instance, you can connect your Encore application directly to this existing database.

## Benefits

Using an existing AWS RDS instance allows you to:
- Maintain data continuity with your existing systems
- Preserve specific database configurations
- Utilize familiar database setups without migration

## Importing an AWS RDS instance

Follow these steps to import your existing AWS RDS instance:

1. Navigate to **Create Environment** in the [Encore Cloud dashboard](https://app.encore.cloud)
2. Select the AWS cloud provider
3. Pick the `AWS Region` your database resides in
3. Choose **Import Existing RDS Instance**
4. Specify your database's `RDS Instance Name`
5. Click the `Resolve` button to validate the instance

Once validated, you can create the environment. When you deploy to this environment, Encore Cloud will automatically connect your application to your imported AWS RDS instance rather than provisioning a new database.

## Mapping existing databases to your Encore app
To access an existing database in your Encore application, you need to specify the name of the existing database when you declare the database in your app. For example, if you have an existing database called `mydb` you can create a reference to it like so:

```typescript
const db = new SQLDatabase("mydb");
```

```go
sqldb.NewDatabase("mydb", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})
```

## Applying migrations to existing databases
Encore uses a table called `schema_migrations` in the public namespace to keep track of which migrations have been applied. If you import an existing database without that table, Encore will create it for you and apply your migrations in order. If the table already exists, Encore expects it to contain exactly two columns:

```
version bigint
dirty boolean
```

If the table exists but has a different schema, you will not be able to import it with Encore at this time. If the table exists with an existing entry, Encore will apply all higher versions in your `migrations` directory to the database.

### Bootstrap migration for existing databases

If you have an existing production database that wasn't previously managed by Encore's migration system, you need to set up a **bootstrap migration** so that new environments (dev, staging, etc.) are created with the same schema, while your existing database is not modified.

**Step 1:** Dump your existing database schema:

```shell
$ pg_dump --schema-only --no-owner --no-privileges your_database > 001_bootstrap.up.sql
```

Review the output and clean it up as needed (remove any database-specific settings, comments, etc.), then place it in your service's `migrations` directory.

**Step 2:** In your **existing** imported database, manually create the `schema_migrations` table and mark the bootstrap migration as already applied:

```sql
CREATE TABLE IF NOT EXISTS schema_migrations (version bigint NOT NULL, dirty boolean NOT NULL);
INSERT INTO schema_migrations (version, dirty) VALUES (1, false);
```

This tells Encore that migration `1` (the bootstrap) has already been applied to this database. Encore will skip it and only run migrations with a higher version number.

**Step 3:** Any future schema changes should be added as new migration files (e.g. `002_add_column.up.sql`). These will be applied to all environments, including the imported database.

<Callout type="info">

This approach ensures that new environments get the full schema from scratch via the bootstrap migration, while your production database continues from where it is without any changes being re-applied.

</Callout>