SPOC-489: Add bidirectional large object migration between native and lolor storage

Makefile

@@ -4,7 +4,8 @@ MODULE_big = lolor
 
 EXTENSION = lolor
 DATA = lolor--1.0.sql \
-	   lolor--1.0--1.2.1.sql lolor--1.2.1--1.2.2.sql
+	   lolor--1.0--1.2.1.sql lolor--1.2.1--1.2.2.sql \
+	   lolor--1.2.2--1.3.sql
 PGFILEDESC = "lolor - drop in large objects replacement for logical replication"
 
 OBJS = src/lolor.o src/lolor_fsstubs.o src/lolor_inv_api.o src/lolor_largeobject.o

README.md

@@ -69,8 +69,30 @@ the following commands to add the tables:
 ./pgedge spock repset-add-table spock_replication_set 'lolor.pg_largeobject_metadata' lolor_db
 ```
 
+### Migrating large objects
+
+Migration from native to lolor is **manual**; migration back is **automatic**
+on `DROP EXTENSION` so no objects are ever lost.
+
+Migrate existing native large objects into lolor storage (requires superuser):
+
+```sql
+CREATE EXTENSION lolor;
+SELECT lolor.migrate_from_native();
+```
+
+Reverse migration happens automatically when the extension is dropped, or can
+be triggered manually:
+
+```sql
+SELECT lolor.migrate_to_native();  -- manual
+DROP EXTENSION lolor;              -- automatic
+```
+
+Both directions preserve original OIDs, owners, ACLs, and data.
+
 ### Limitations
 
 - Native large object functionality cannot be used while you are using the lolor extension.
-- Native large object migration to the lolor feature is not available yet.
 - lolor does not support the following statements: `ALTER LARGE OBJECT`, `GRANT ON LARGE OBJECT`, `COMMENT ON LARGE OBJECT`, and `REVOKE ON LARGE OBJECT`.
+- Migration procedures are currently safe only in master-replica configurations. Multi-master migration is not yet supported due to OID encoding constraints.

docs/index.md

@@ -16,8 +16,50 @@ Postgres large objects allow you to store large files within the database. Each
 Use of the `lolor` extension requires Postgres 16 or newer.
 
 
+## Migrating large objects
+
+Migration from native to lolor storage is **manual** — you decide when to move
+existing large objects.  Migration back to native is **automatic** — dropping
+the extension moves all objects back so nothing is lost.
+
+### Native to lolor (manual)
+
+If your database already contains native Postgres large objects, call
+`migrate_from_native()` after enabling the extension.  The migration preserves
+original OIDs, owners, ACLs, and data, so existing application references remain
+valid.
+
+```sql
+CREATE EXTENSION lolor;
+SELECT lolor.migrate_from_native();
+```
+
+The function returns the number of large objects migrated.  It is safe to call
+when there are no native large objects.  This step is intentionally not
+automatic: it requires superuser privileges and should be performed during a
+maintenance window.
+
+### Lolor to native (automatic on DROP EXTENSION)
+
+Large objects are automatically migrated back to native Postgres storage when the
+extension is dropped:
+
+```sql
+DROP EXTENSION lolor;
+```
+
+This ensures that no large objects are lost if the extension is removed.  You
+can also trigger the reverse migration manually while the extension is still
+installed:
+
+```sql
+SELECT lolor.migrate_to_native();
+```
+
+Both paths preserve OIDs, owners, ACLs, and data.
+
 ## Limitations
 
 - Native Postgres large object functionality cannot be used while you are using the lolor extension.
-- Native large object migration to the lolor feature is not available yet.
 - lolor does not support the following statements: `ALTER LARGE OBJECT`, `GRANT ON LARGE OBJECT`, `COMMENT ON LARGE OBJECT`, and `REVOKE ON LARGE OBJECT`.
+- The migration procedures (`migrate_from_native`, `migrate_to_native`) are currently safe only in master-replica configurations. In multi-master setups, migrated OIDs (which lack node-encoding) may conflict with OIDs on other nodes.