AI agents: use the documentation index at llms.txt to locate machine-readable pages. This section is indexed by https://docs.particular.net/persistence/llms.txt. The markdown version of this page is served as plain text. An MCP server at /mcp serves the same content via the search_docs and read_doc tools; it is read-only and needs no credentials. Markdown versions of documentation pages are available by appending .md to the page URL. Directory URLs use index.md. They are served as text/plain because some retrieval backends reject text/markdown.

Migrating from NHibernate to SQL persister

Component:
Sql Persistence

Schema

The database schemas for NHibernate and SQL persisters are not compatible.

Review the schema generated by each persister before migrating data. For SQL Server, see the scripting pages:

Sagas

  • NHibernate: maps saga data to relational table columns.
  • SQL Persistence: serializes saga data and metadata as JSON, with saga IDs and correlation values stored separately.

Subscriptions

  • NHibernate: stores subscriptions in a Subscription table by default.
  • SQL Persistence: uses a separate <table_prefix>SubscriptionData table for each logical endpoint. By default, the table prefix is the endpoint name with periods replaced by underscores; it can be configured using the table prefix setting.

Timeouts

  • NHibernate: stores timeouts in a TimeoutEntity table with an Endpoint column.
  • SQL Persistence: uses a separate <table_prefix>TimeoutData table for each endpoint.

Outbox

  • NHibernate: stores outbox records in an OutboxRecord table shared by endpoints. In later versions, the endpoint name is prepended to the message ID.
  • SQL Persistence: uses a separate <table_prefix>OutboxData table for each logical endpoint.

Outbox retention

Longer outbox retention and high message throughput can increase the amount of data to migrate and migration time. Keeping the retention period as low as possible is recommended.

Data migration

Conversion

Subscription, timeout, and outbox data can be migrated with custom scripts that map the source schema to the target schema. Use the generated target schema and account for configured table names; this page does not provide ready-made conversion scripts.

Saga state migration is more complex. NHibernate maps saga properties to relational columns, while SQL Persistence stores saga data and metadata as JSON and stores correlation values separately. Create and validate mappings for each saga type, preserving saga IDs and correlation values.

Migration downtime

Migration downtime depends on:

  • The deployment complexity
  • Whether custom saga migration mappings are needed
  • The data set size
  • The complexity of saga state
  • Whether outbox, timeout, and subscription data must be migrated

In this article