|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Migrations Couchbase Provider |
| 4 | +nav_order: 2 |
| 5 | +--- |
| 6 | + |
| 7 | +# Hyperbee Migrations Couchbase Provider |
| 8 | + |
| 9 | +Welcome to `Hyperbee.Migrations.Providers.Couchbase`, an extension to the foundational `Hyperbee.Migrations` library. This extension is specifically designed to incorporate support for Couchbase. |
| 10 | + |
| 11 | +## Introduction |
| 12 | + |
| 13 | +The `Hyperbee.Migrations.Providers.Couchbase` library is an tool for developers seeking to perform database migrations in a Couchbase environment using the `Hyperbee.Migrations` library. This library furnishes a comprehensive suite of tools and functionalities that integrate effortlessly with `Hyperbee.Migrations`, thereby enabling developers to harness the robust capabilities of Couchbase in their applications. |
| 14 | + |
| 15 | +The `Hyperbee.Migrations.Providers.Couchbase` library is equipped to assist developers in creating, updating, and managing their Couchbase databases. With the aid of this library, developers can concentrate their efforts on the development of their application, while the library handles the intricacies of database management. |
| 16 | + |
| 17 | +We are committed to continuous improvement and feature enhancement. We appreciate your interest and look forward to your valuable feedback. |
| 18 | + |
| 19 | +Please see [Hyperbee Migrations' Read Me](index.md) for non-database specific usage. |
| 20 | + |
| 21 | + |
| 22 | +## Concepts |
| 23 | + |
| 24 | +Every migration has several elements you need to be aware of. |
| 25 | + |
| 26 | +* You can create a StartMethod method that resolves to **Task \<bool>**, in order to tell the runner when to start. |
| 27 | +* You can create a StopMethod method that resolves to **Task \<bool>**, in order to tell the runner when to stop. |
| 28 | +* You can set whether or not you want to journal the migration. |
| 29 | + |
| 30 | +## Configuration |
| 31 | + |
| 32 | +### Add Couchbase Services |
| 33 | +```c# |
| 34 | +// In Startup.cs |
| 35 | +public void ConfigureServices(IServiceCollection services) |
| 36 | +{ |
| 37 | + // Configure MongoDB |
| 38 | + services.AddCouchbase(); |
| 39 | + |
| 40 | + // Add the MigrationRunner |
| 41 | + services.AddCouchbaseMigrations(...); |
| 42 | +} |
| 43 | + |
| 44 | +public void Configure(IApplicationBuilder app, ...) |
| 45 | +{ |
| 46 | + // Run pending migrations. |
| 47 | + var migrationService = app.ApplicationServices.GetRequiredService<MigrationRunner>(); |
| 48 | + migrationService.Run(); |
| 49 | +} |
| 50 | +``` |
| 51 | +### Preventing simultaneous migrations |
| 52 | + |
| 53 | +By default, Hyperbee Migrations prevents parallel migration runner execution. If you have 2 instances of your |
| 54 | +app running, and both try to run migrations, Hyperbee Migrations will prevent the second instance from running |
| 55 | +migrations and will log a warning. |
| 56 | + |
| 57 | +Hyperbee Migrations accomplishes this by using a distributed lock at the database layer. The default |
| 58 | +implementation is based on the provider and uses a timeout and an auto-renewal interval to prevent orphaned locks. |
| 59 | + |
| 60 | +If you want to change this behavior you can override the default options: |
| 61 | + |
| 62 | +```c# |
| 63 | +services.AddCouchbaseMigrations( options => |
| 64 | +{ |
| 65 | + // Locking is on by default. Set to false to allow simultaneous runners - but don't be that guy. |
| 66 | + options.LockingEnabled = false; |
| 67 | + |
| 68 | + // You can change locking behavior. Defaults shown. |
| 69 | + options.LockMaxLifetime = TimeSpan.FromHours( 1 ); // max time-to-live |
| 70 | + options.LockExpireInterval = TimeSpan.FromMinutes( 5 ); // expire heartbeat |
| 71 | + options.LockRenewInterval = TimeSpan.FromMinutes( 2 ); // renewal heartbeat |
| 72 | +}); |
| 73 | +``` |
| 74 | + |
| 75 | +### Migrations |
| 76 | +Hyperbee Migrations relies on dependency injection to pass services to your migration. |
| 77 | + |
| 78 | +```c# |
| 79 | +[Migration(1)] |
| 80 | +public class MyMigration : Migration |
| 81 | +{ |
| 82 | + private IClusterProvider _clusterProvider; |
| 83 | + private ILogger _logger; |
| 84 | + |
| 85 | + // Injected services registered with the container |
| 86 | + public MyMigration( IClusterProvider clusterProvider, ILogger<MyMigration> logger ) |
| 87 | + { |
| 88 | + _clusterProvider = clusterProvider; |
| 89 | + _logger = logger; |
| 90 | + } |
| 91 | + |
| 92 | + public async override Task UpAsync( CancellationToken cancellationToken = default ) |
| 93 | + { |
| 94 | + // do something with clusterProvider |
| 95 | + } |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +### Dependency Injection |
| 100 | + |
| 101 | +The MongoDB provider also provides a `MongoDBResourceRunner<MyMigration>` that adds helpful functionality when using embedded resources. |
| 102 | + - `StatementsFromAsync` run SQL++ (N1QL) statements for different bucket/scope/collections within Couchbase. |
| 103 | + - `DocumentsFromAsync` Upserts documents into Couchbase. This is normally use for pre-seeding. |
| 104 | + - `StartMethod` determines when the migration should start (optional) |
| 105 | + - `StopMethod` determines when the migration should stop (optional) |
| 106 | + - `false` determines if you want to journal (default = true) |
| 107 | + |
| 108 | +```c# |
| 109 | +[Migration(1, "StartMethod", "StopMethod", false)] |
| 110 | +public class MyMigration : Migration |
| 111 | +{ |
| 112 | + private readonly CouchbaseResourceRunner<MyMigration> _resourceRunner; |
| 113 | + |
| 114 | + public CreateInitialBuckets( CouchbaseResourceRunner<MyMigration> resourceRunner ) |
| 115 | + { |
| 116 | + _resourceRunner = resourceRunner; |
| 117 | + } |
| 118 | + |
| 119 | + public override async Task UpAsync( CancellationToken cancellationToken = default ) |
| 120 | + { |
| 121 | + // run a `resource` migration to create initial buckets and state. |
| 122 | + // resource migrations are atypical; prefer `n1ql` migrations. |
| 123 | +
|
| 124 | + await _resourceRunner.StatementsFromAsync( new[] |
| 125 | + { |
| 126 | + "statements.json", |
| 127 | + "migrationbucket/statements.json" |
| 128 | + }, |
| 129 | + cancellationToken |
| 130 | + ); |
| 131 | + |
| 132 | + await _resourceRunner.DocumentsFromAsync( new[] |
| 133 | + { |
| 134 | + "migrationbucket/_default" |
| 135 | + }, |
| 136 | + cancellationToken |
| 137 | + ); |
| 138 | + } |
| 139 | + |
| 140 | + public Task<bool> StartMethod() |
| 141 | + { |
| 142 | + //create process here |
| 143 | + } |
| 144 | + |
| 145 | + public Task<bool> StopMethod() |
| 146 | + { |
| 147 | + //create process here |
| 148 | + } |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +### Profiles |
| 153 | + |
| 154 | +There are times when you may want to scope migrations to specific environments. To allow this Hyperbee Migrations |
| 155 | +supports profiles. For instance, some migrations might only run during development. By decorating your migration |
| 156 | +with the profile of _"development"_ and setting **options** to include only that profile, you can control which |
| 157 | +migrations run in which environments. |
| 158 | + |
| 159 | +```c# |
| 160 | +[Migration(3, "development")] |
| 161 | +public class DevelopmentOnlyMigration : Migration |
| 162 | +{ |
| 163 | + public async override Task UpAsync( CancellationToken cancellationToken = default ) |
| 164 | + { |
| 165 | + // do something nice for local developers |
| 166 | + } |
| 167 | +} |
| 168 | + |
| 169 | +... |
| 170 | + |
| 171 | +// In Startup.cs |
| 172 | +public void ConfigureServices( IServiceCollection services ) |
| 173 | +{ |
| 174 | + services.AddCouchbaseMigrations( options => |
| 175 | + { |
| 176 | + // Configure to only run development migrations |
| 177 | + options.Profiles = new[] { "development" } }; |
| 178 | + }); |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +A migration may belong to multiple profiles. |
| 183 | + |
| 184 | +```c# |
| 185 | +[Migration(3, "development", "staging")] |
| 186 | +public class TargetedMigration : Migration |
| 187 | +{ |
| 188 | + // ... |
| 189 | +} |
| 190 | +``` |
| 191 | + |
| 192 | +### Cron Settings |
| 193 | +```c# |
| 194 | +[Migration(3, "StartMethod", "StopMethod")] |
| 195 | +public class DevelopmentOnlyMigration : Migration |
| 196 | +{ |
| 197 | + public async override Task UpAsync( CancellationToken cancellationToken = default ) |
| 198 | + { |
| 199 | + // do something nice for local developers |
| 200 | + } |
| 201 | + |
| 202 | + public async Task<bool> StartMethod() |
| 203 | + { |
| 204 | + var helper = new MigrationCronHelper(); |
| 205 | + var results = await helper.CronDelayAsync( "* * * * *" ); |
| 206 | + return results; |
| 207 | + } |
| 208 | + |
| 209 | + public Task<bool> StopMethod() |
| 210 | + { |
| 211 | + var helper = new MigrationCronHelper(); |
| 212 | + var results = await helper.CronDelayAsync( "4 * * * *" ); |
| 213 | + return results; |
| 214 | + } |
| 215 | +} |
| 216 | +``` |
| 217 | + |
| 218 | +### Journaling |
| 219 | +Journaling is a bool indicator. Null indicates there are no start or stop methods. |
| 220 | +```c# |
| 221 | +[Migration(3, null, null, false)] |
| 222 | +public class DevelopmentOnlyMigration : Migration |
| 223 | +{ |
| 224 | + public async override Task UpAsync( CancellationToken cancellationToken = default ) |
| 225 | + { |
| 226 | + // do something nice for local developers |
| 227 | + } |
| 228 | +} |
0 commit comments