Skip to content

Commit 4346859

Browse files
ArkatufusArkatufus
authored
Update RELEASE_NOTES.md for 1.5.2-beta3 release (#228)
1 parent 6893233 commit 4346859

File tree

2 files changed

+248
-24
lines changed

2 files changed

+248
-24
lines changed

‎README.md

Lines changed: 214 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,43 @@ This is a port of the amazing [akka-persistence-jdbc](https://github.com/akka/ak
66

77
Please read the documentation carefully. Some features may be specific to use case and have trade-offs (namely, compatibility modes)
88

9-
## Notes
10-
11-
### This Is Still a Beta
12-
13-
Please note this is still considered 'work in progress' and only used if one understands the risks. While the TCK Specs pass you should still test in a 'safe' non-production environment carefully before deciding to fully deploy.
14-
15-
### Suitable For Greenfield Projects Only
16-
17-
Until backward compatibility is properly tested and documented, it is recommended to use this plugin only on new greenfield projects that does not rely on existing persisted data.
18-
19-
## Setup
20-
21-
### The Easy Way, Using `Akka.Hosting`
9+
> ### This Is Still a Beta
10+
>
11+
> Please note this is still considered 'work in progress' and only used if one understands the risks. While the TCK Specs pass you should still test in a 'safe' non-production environment carefully before deciding to fully deploy.
12+
13+
> ### Suitable For Greenfield Projects Only
14+
>
15+
>Until backward compatibility is properly tested and documented, it is recommended to use this plugin only on new greenfield projects that does not rely on existing persisted data.
16+
17+
# Table Of Content
18+
- [Akka.Persistence.Sql](#akkapersistencesql)
19+
- [Setup](#setup)
20+
* [The Easy Way, Using `Akka.Hosting`](#the-easy-way-using-akkahosting)
21+
* [The Classic Way, Using HOCON](#the-classic-way-using-hocon)
22+
* [Supported Database Providers](#supported-database-providers)
23+
+ [Tested Database Providers](#tested-database-providers)
24+
+ [Supported By Linq2Db But Untested In Akka.Persistence ](#supported-by-linq2db-but-untested-in-akkapersistence)
25+
- [Migration Guide](#migration-guide)
26+
* [Migrating Using Compatibility Mode](#migrating-using-compatibility-mode)
27+
+ [Akka.Hosting](#akkahosting)
28+
+ [HOCON](#hocon)
29+
* [Migrating To Tag Table Based Tag Query](#migrating-to-tag-table-based-tag-query)
30+
* [Migrating To Enable WriterUuid Anti-Corruption Layer Feature](#migrating-to-enable-writeruuid-anti-corruption-layer-feature)
31+
- [Features/Architecture](#featuresarchitecture)
32+
* [Currently Implemented](#currently-implemented)
33+
* [Incomplete](#incomplete)
34+
- [Performance](#performance)
35+
- [Sql.Common Compatibility modes](#sqlcommon-compatibility-modes)
36+
- [Configuration](#configuration)
37+
* [Journal](#journal)
38+
* [Snapshot Store](#snapshot-store)
39+
- [Building this solution](#building-this-solution)
40+
+ [Conventions](#conventions)
41+
+ [Release Notes, Version Numbers, Etc](#release-notes-version-numbers-etc)
42+
43+
# Setup
44+
45+
## The Easy Way, Using `Akka.Hosting`
2246

2347
Assuming a MS SQL Server 2019 setup:
2448
```csharp
@@ -33,7 +57,7 @@ var host = new HostBuilder()
3357
})
3458
```
3559

36-
### The Classic Way, Using HOCON
60+
## The Classic Way, Using HOCON
3761

3862
These are the minimum HOCON configuration you need to start using Akka.Persistence.Sql:
3963
```hocon
@@ -71,9 +95,9 @@ akka.persistence {
7195
- MS SQLite
7296
- System.Data.SQLite
7397
- PostgreSQL using binary payload
74-
75-
### Supported By Linq2Db But Untested In Akka.Persistence
7698
- MySql
99+
100+
### Supported By Linq2Db But Untested In Akka.Persistence
77101
- Firebird
78102
- Microsoft Access OleDB
79103
- Microsoft Access ODBC
@@ -84,7 +108,173 @@ akka.persistence {
84108
- SAP HANA
85109
- ClickHouse
86110

87-
## Features/Architecture
111+
# Migration Guide
112+
113+
> [!Warning]
114+
> Some of the steps in this guide might change the database schema of your persistent
115+
> database, making it really hard to revert any changes.
116+
>
117+
> Always do a database backup before attempting to do any of these migration steps.
118+
>
119+
> Always test the result of any migration on a development environment
120+
121+
## Migrating Using Compatibility Mode
122+
123+
Supported `Akka.Persistence.Sql.Common` targets
124+
125+
| Plugin | Server |
126+
|-------------------------------|----------------------|
127+
| `Akka.Persistence.SqlServer` | Microsoft SQL Server |
128+
| `Akka.Persistence.PostgreSql` | PostgreSql |
129+
| `Akka.Persistence.MySql` | MySql |
130+
| `Akka.Persistence.Sqlite` | SqLite |
131+
132+
### Akka.Hosting
133+
134+
To migrate to `Akka.Persistence.Sql` from supported `Akka.Persistence.Sql.Common` plugins, supply the required parameters:
135+
136+
```csharp
137+
builder
138+
.WithSqlPersistence(
139+
connectionString: "my-connection-string",
140+
providerName: ProviderName.SqlServer2019,
141+
databaseMapping: DatabaseMapping.SqlServer,
142+
tagStorageMode: TagMode.Csv,
143+
deleteCompatibilityMode: true,
144+
useWriterUuidColumn: false,
145+
autoInitialize: false
146+
);
147+
```
148+
149+
* `databaseMapping` - Set this parameter according to this table:
150+
151+
| Plugin | databaseMapping |
152+
|------------|------------------------------|
153+
| SqlServer | `DatabaseMapping.SqlServer` |
154+
| PostgreSql | `DatabaseMapping.PostgreSql` |
155+
| MySql | `DatabaseMapping.MySql` |
156+
| Sqlite | `DatabaseMapping.SqLite` |
157+
158+
* `tagStoreMode`
159+
* Set to `TagMode.Csv` if you do not or have not migrated your database to use tag table.
160+
* Set to `TagMode.TagTable` if you migrated your database to use tag table.
161+
* `deleteCompatibilityMode` - always set this parameter to `true`
162+
* `useWriterUuidColumn`
163+
* Set to `false` if you do not or have not migrated your database to use `WriterUuid` feature
164+
* Set to `true` if you migrated your database to use `WriterUuid`.
165+
* `autoInitialize` - always set this to `false` to prevent any schema modification.
166+
167+
### HOCON
168+
169+
```hocon
170+
akka.persistence {
171+
journal {
172+
plugin = "akka.persistence.journal.sql"
173+
sql {
174+
connection-string = "{database-connection-string}"
175+
provider-name = "{provider-name}"
176+
177+
# Required for migration, do not change existing schema
178+
auto-initialize = false
179+
180+
# Required for migration
181+
# Set to "sqlite", "sql-server", "mysql", or "postgresql"
182+
# depending on the plugin you're migrating from
183+
table-mapping = sql-server
184+
185+
# Required if you did not migrate your database to tag table mode
186+
tag-write-mode = Csv
187+
188+
# Required for migration
189+
delete-compatibility-mode = true
190+
191+
# Required if you did not migrate your database to use WriterUuid
192+
{table-mapping-name}.journal.use-writer-uuid-column = false
193+
}
194+
}
195+
query.journal.sql {
196+
connection-string = "{database-connection-string}"
197+
provider-name = "{provider-name}"
198+
199+
# Required if you did not migrate your database to tag table mode
200+
tag-write-mode = Csv
201+
}
202+
snapshot-store {
203+
plugin = "akka.persistence.snapshot-store.sql"
204+
sql {
205+
connection-string = "{database-connection-string}"
206+
provider-name = "{provider-name}"
207+
208+
# Required for migration, do not change existing schema
209+
auto-initialize = false
210+
211+
# Required for migration
212+
# Set to "sqlite", "sql-server", "mysql", or "postgresql"
213+
# depending on the plugin you're migrating from
214+
table-mapping = sql-server
215+
}
216+
}
217+
}
218+
```
219+
220+
## Migrating To Tag Table Based Tag Query
221+
222+
> [!Warning]
223+
> This guide WILL change the database schema of your persistent database.
224+
>
225+
> Always do a database backup before attempting to do any of these migration steps.
226+
227+
To migrate your database to use the new tag table based tag query feature, follow these steps:
228+
229+
1. Download the migration SQL scripts for your particular database type from the "Sql Scrips" folder in `Akka.Persistence.Sql` repository.
230+
2. Down your cluster.
231+
3. Do a database backup and save the backup file somewhere safe.
232+
4. Execute SQL script "1_Migration_Setup.sql" against your database.
233+
5. Execute SQL script "2_Migration.sql" against your database.
234+
6. (Optional) Execute SQL script "3_Post_Migration_Cleanup.sql" against your database.
235+
7. Apply migration steps in [Migrating Using Compatibility Mode](#migrating-using-compatibility-mode) section.
236+
8. Bring the cluster back up.
237+
238+
These SQL scripts are designed to be idempotent and can be run on the same database without creating any side effects.
239+
240+
## Migrating To Enable WriterUuid Anti-Corruption Layer Feature
241+
242+
> [!Warning]
243+
> This guide WILL change the database schema of your persistent database.
244+
>
245+
> Always do a database backup before attempting to do any of these migration steps.
246+
247+
To migrate your database to use the new WriterUuid feature, follow these steps:
248+
249+
1. Do a database backup and save the backup file somewhere safe.
250+
2. Down your cluster.
251+
3. Execute this SQL script against your database:
252+
```sql
253+
ALTER TABLE [journal_table_name] ADD writer_uuid VARCHAR(128);
254+
```
255+
4. Modify the database mapping configuration to enable the feature:
256+
257+
**Using Akka.Hosting**
258+
259+
```csharp
260+
builder
261+
.WithSqlPersistence(
262+
connectionString: "my-connection-string",
263+
// ...
264+
useWriterUuidColumn: true // Use this setting
265+
);
266+
```
267+
268+
**Using HOCON**
269+
270+
```HOCON
271+
# replace {mapping-name} with "sqlite", "sql-server", "mysql", or "postgresql"
272+
akka.persistence.journal.sql.{mapping-name}.journal.use-writer-uuid-column = true
273+
```
274+
5. Apply migration steps in [Migrating Using Compatibility Mode](#migrating-using-compatibility-mode) section.
275+
6. Bring the cluster back up.
276+
277+
# Features/Architecture
88278

89279
- Akka.Streams used aggressively for tune-able blocking overhead.
90280
- Up to `parallelism` writers write pushed messages
@@ -138,9 +328,9 @@ akka.persistence {
138328

139329
- Tests for Schema Usage
140330
- Cleanup of Configuration classes/fallbacks.
141-
- Should still be usable in most common scenarios including multiple configuration instances: see [`SqlServerCustomConfigSpec`](src/Akka.Persistence.Sql.Tests/SqlServer/SQLServerJournalCustomConfigSpec.cs) for test and examples.
331+
- Should still be usable in most common scenarios including multiple configuration instances: see [`SqlServerCustomConfigSpec`](src/Akka.Persistence.Sql.Tests/SqlServer/SqlServerJournalCustomConfigSpec.cs) for test and examples.
142332

143-
## Performance
333+
# Performance
144334

145335
Tests based on AMD Ryzen 9 3900X, 32GB Ram, Windows 10 Version 22H2.
146336
Databases running on Docker WSL2.
@@ -164,7 +354,7 @@ All numbers are in msg/sec.
164354
| RecoveringFour | 86107 | 73218 | 66512 | 77.24% | 90.84% |
165355
| RecoveringTwo | 60730 | 53062 | 43325 | 71.34% | 81.65% |
166356

167-
## Sql.Common Compatibility modes
357+
# Sql.Common Compatibility modes
168358

169359
- Delete Compatibility mode is available.
170360
- This mode will utilize a `journal_metadata` table containing the last sequence number
@@ -177,9 +367,9 @@ All numbers are in msg/sec.
177367
- **This all happens in a transaction**
178368
- In SQL Server this can cause issues because of pagelocks/etc.
179369

180-
## Configuration
370+
# Configuration
181371

182-
### Journal
372+
## Journal
183373

184374
Please note that you -must- provide a Connection String (`connection-string`) and Provider name (`provider-name`).
185375

@@ -599,7 +789,7 @@ akka.persistence {
599789

600790
```
601791

602-
### Snapshot Store
792+
## Snapshot Store
603793

604794
Please note that you -must- provide a Connection String and Provider name.
605795

@@ -724,7 +914,7 @@ akka.persistence {
724914
}
725915
```
726916

727-
## Building this solution
917+
# Building this solution
728918

729919
To run the build script associated with this solution, execute the following:
730920

‎RELEASE_NOTES.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,37 @@
1+
#### 1.5.2-beta3 April 19 2023 ###
2+
3+
> **NOTE: Database schema changes**
4+
>
5+
> 1.5.2-beta2 package should be considered as deprecated. If you experimented with 1.5.2-beta1 and/or 1.5.2-beta2, you will need to drop existing persistence tables and recreate them using 1.5.2-beta3
6+
7+
* [Fix SQL scripts for database table constraint and indices](https://github.com/akkadotnet/Akka.Persistence.Sql/pull/220)
8+
* [Add official MySql support](https://github.com/akkadotnet/Akka.Persistence.Sql/pull/221)
9+
* [Optimize sequence number and tag query](https://github.com/akkadotnet/Akka.Persistence.Sql/pull/222)
10+
* [Optimize tag query by avoiding multiple DB queries](https://github.com/akkadotnet/Akka.Persistence.Sql/pull/223)
11+
* [Add missing migration support to hosting extension method](https://github.com/akkadotnet/Akka.Persistence.Sql/pull/225)
12+
13+
This beta version introduces database schema optimization to:
14+
* Improve the tag table based query performance even more.
15+
* Improve inter-compatibility with other SQL persistence plugins.
16+
17+
**Tag Query Benchmark**
18+
19+
Benchmark is performed on a worst possible scenario:
20+
* Event journal table with 3 million row entries
21+
* Tagged events near the end of the table
22+
* Numbers are measured as the time required to complete one operation (complete retrieval of N tagged events).
23+
24+
| Tag Count | TagMode | Mean | Error | StdDev |
25+
|-----------|--------- |-------------:|-----------:|-----------:|
26+
| 10 | Csv | 1,760.393 ms | 27.1970 ms | 25.4401 ms |
27+
| 100 | Csv | 1,766.355 ms | 25.0182 ms | 23.4021 ms |
28+
| 1000 | Csv | 1,755.960 ms | 33.8171 ms | 34.7276 ms |
29+
| 10000 | Csv | 1,905.026 ms | 22.3564 ms | 20.9122 ms |
30+
| 10 | TagTable | 2.336 ms | 0.0389 ms | 0.0344 ms |
31+
| 100 | TagTable | 3.943 ms | 0.0705 ms | 0.0660 ms |
32+
| 1000 | TagTable | 18.597 ms | 0.3570 ms | 0.3506 ms |
33+
| 10000 | TagTable | 184.446 ms | 3.3447 ms | 2.9650 ms |
34+
135
#### 1.5.2-beta2 April 14 2023 ###
236

337
> **NOTE: Database schema changes**

0 commit comments

Comments
 (0)