Skip to content

Commit 8ef156d

Browse files
committed
docs: upgrade index creation instructions
1 parent 23c157b commit 8ef156d

File tree

1 file changed

+25
-9
lines changed

1 file changed

+25
-9
lines changed

README.md.gotmpl

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1492,7 +1492,8 @@ Use [obtain-oidc-id-token](https://github.com/codefresh-io/steps/blob/822afc0a9a
14921492

14931493
Sometimes, in new releases of Codefresh On-Prem, index requirements change. When this happens, it's mentioned in the [Upgrading section](#upgrading) for the specific release.
14941494

1495-
> ℹ️ If you're upgrading from version `X` to version `Y`, and index requirements were updated in any of the intermediate versions, you only need to align your indexes with the index requirements of version `Y`. To do that, follow [Index alignment](#index-alignment) instructions.
1495+
> [!TIP]
1496+
> If you're upgrading from version `X` to version `Y`, and index requirements were updated in any of the intermediate versions, you only need to align your indexes with the index requirements of version `Y`. To do that, follow [Index alignment](#index-alignment) instructions.
14961497

14971498
### Index alignment
14981499

@@ -1515,11 +1516,12 @@ indexes
15151516
**Overview of the index alignment process:**
15161517

15171518
1. Identify the differences between the indexes in your MongoDB instance and the required index definitions.
1518-
2. Create any missing indexes one by one. (It's important not to create them in bulk.)
1519+
2. Create any missing indexes.
15191520
3. Perform the upgrade of Codefresh On-Prem installation.
15201521
4. Then remove any unnecessary indexes.
15211522

1522-
> ⚠️ **Note! Any changes to indexes should be performed during a defined maintenance window or during periods of lowest traffic to MongoDB.**
1523+
> [!IMPORTANT]
1524+
> Any changes to indexes should be performed during a defined maintenance window or during periods of lowest traffic to MongoDB.**
15231525
>
15241526
> Building indexes during time periods where the target collection is under heavy write load can result in reduced write performance and longer index builds. ([*Source: MongoDB official documentation*](https://www.mongodb.com/docs/manual/core/index-creation/#index-build-impact-on-database-performance))
15251527
>
@@ -1542,19 +1544,32 @@ mongosh "<connection_string>"
15421544
db.getSiblingDB('<db_name>').getCollection('<collection_name>').getIndexes()
15431545
```
15441546

1545-
- Compare your indexes with the required indexes for the target release, and adjust them by creating any missing indexes or removing any unnecessary ones
1547+
- Compare your indexes with the required indexes for the target release, and adjust them by creating any missing indexes or removing any unnecessary ones.
15461548

15471549
**Index creation**
15481550

1549-
> ⚠ **Note! Always create indexes sequentially, one by one. Don't create them in bulk.**
1551+
- To create an indexes, we recommend using the `createIndexes` command ([ref](https://www.mongodb.com/docs/manual/reference/command/createIndexes/)):
15501552

1551-
- To create an index, use the `createIndex()` method:
1553+
> [!IMPORTANT]
1554+
> We recommend to create indexes in batches of 3 indexes at a time.
1555+
> However, it's highly recommended before creating indexes in production DB to test performance impact on a staging instance with prod-like amount of data.
1556+
>
1557+
> Previous command should be completed before starting the next batch.
15521558

15531559
```js
1554-
db.getSiblingDB('<db_name>').getCollection('<collection_name>').createIndex(<keys_object>, <options_object>)
1560+
db.getSiblingDB('<db_name>').runCommand(
1561+
{
1562+
createIndexes: '<collection_name>',
1563+
indexes: [
1564+
{ ... }, // Index definition from the doc above
1565+
{ ... }, // Index definition from the doc above
1566+
{ ... } // Index definition from the doc above
1567+
],
1568+
}
1569+
)
15551570
```
15561571

1557-
After executing the `createIndex()` command, you should see a result indicating that the index was created successfully.
1572+
After executing the command, you should see a result indicating that the indexes were created successfully.
15581573

15591574
**Index removal**
15601575

@@ -1568,7 +1583,8 @@ db.getSiblingDB('<db_name>').getCollection('<collection_name>').dropIndex('<inde
15681583

15691584
If you're hosting MongoDB on [Atlas](https://www.mongodb.com/atlas/database), use the following [Manage Indexes](https://www.mongodb.com/docs/atlas/atlas-ui/indexes/) guide to View, Create or Remove indexes.
15701585

1571-
> ⚠️ **Important!** In Atlas, for production environments, it is recommended to use rolling index builds by enabling the "Build index via rolling process" checkbox. ([*MongoDB official documentation*](https://www.mongodb.com/docs/v6.0/tutorial/build-indexes-on-replica-sets/))
1586+
> [!IMPORTANT]
1587+
> In Atlas, for production environments, it may be recommended to use rolling index builds by enabling the "Build index via rolling process" checkbox. ([*MongoDB official documentation*](https://www.mongodb.com/docs/v7.0/tutorial/build-indexes-on-replica-sets/))
15721588

15731589
## Upgrading
15741590

0 commit comments

Comments
 (0)