The permify repair datastore command helps prevent PostgreSQL XID wraparound issues by safely advancing the transaction ID counter. This is essential after database migrations or when dealing with XID-related problems.

​
Overview

XID (Transaction ID) wraparound is a PostgreSQL issue that occurs when the database’s transaction counter approaches its maximum value. This command provides a safe solution by:
  • Analyzing maximum referenced XIDs in transactions table
  • Advancing PostgreSQL’s XID counter to stay ahead of referenced XIDs
  • Using safe batch processing to avoid performance impact
Important: This approach does NOT modify existing data, only advances the XID counter.

​
Usage

permify repair datastore [flags]

​
Required Flags

FlagDescriptionExample
--database-uriDatabase connection URIpostgres://user:pass@localhost:5432/permify

​
Optional Flags

FlagDefaultDescription
--database-enginepostgresDatabase engine (only postgres supported)
--batch-size1000Batch size for XID advancement
--dry-runfalsePerform a dry run without making changes
--verbosetrueEnable verbose logging
--retries3Maximum number of retries

​
Examples

​
Basic Usage

permify repair datastore \
  --database-uri "postgres://user:pass@localhost:5432/permify"

​
Dry Run

Test what would be changed without making actual modifications: 
permify repair datastore \
  --database-uri "postgres://user:pass@localhost:5432/permify" \
  --dry-run

​
Custom Batch Size

Use a smaller batch size for production environments: 
permify repair datastore \
  --database-uri "postgres://user:pass@localhost:5432/permify" \
  --batch-size 500

​
How It Works

  1. Current XID Check: Gets the current PostgreSQL transaction ID using pg_current_xact_id()
  2. Reference Analysis: Finds the maximum transaction ID referenced in the transactions table
  3. Gap Calculation: Calculates the difference and adds a safety buffer
  4. Batch Processing: Advances the XID counter in configurable batches to minimize performance impact

​
When to Use

  • After database migrations
  • When PostgreSQL warns about XID wraparound
  • As a preventive measure in high-transaction environments
  • When encountering XID-related errors

​
Safety Features

  • Dry Run Mode: Test changes before applying them
  • Batch Processing: Avoids overwhelming the database
  • Retry Logic: Handles temporary failures gracefully
  • Verbose Logging: Provides detailed progress information
  • Data Preservation: Never modifies existing application data

​
Output Example

INFO Starting PostgreSQL XID counter repair database_uri=postgres://*** batch_size=1000 dry_run=false max_retries=3
INFO Starting PostgreSQL transaction ID counter repair dry_run=false batch_size=1000
INFO Current PostgreSQL transaction ID current_xid=99902
INFO Maximum referenced transaction ID max_referenced_xid=125000
INFO Advancing transaction ID counter by delta counter_delta=26098
INFO Advanced XID counter batch batch_size=1000 remaining=25098
INFO Advanced XID counter batch batch_size=1000 remaining=24098
...
INFO Transaction ID counter advancement completed total_advanced=26098
INFO Repair completed successfully duration=2.3s created_tx_id_fixed=26098 errors=0
INFO XID counter repair completed successfully! Advanced XID counter to prevent wraparound issues.

​
Troubleshooting

​
Common Issues

Connection Error 
failed to create PostgreSQL instance: connection failed
  • Verify database URI is correct
  • Ensure PostgreSQL is running and accessible
Permission Error 
failed to advance XID counter: permission denied
  • Ensure database user has sufficient privileges
  • User needs ability to execute pg_current_xact_id() and transaction operations

​
Best Practices

  • Always run with --dry-run first in production
  • Use appropriate --batch-size for your environment
  • Monitor PostgreSQL logs during execution
  • Schedule regular maintenance to prevent XID buildup
  • Keep database backups before running repair operations