rt-serializer(8)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

💖 rt-serializer(8) — the Request Tracker Reference glow-up 💖

okay bestie, gather round, because this is the tool that dumps your ENTIRE RT database out to disk so you can yeet it into some other RT instance later. it lives in the Request Tracker reference pages (that's the manual name, mwah) and it is, lowkey, iconic. ✨

🌸 NAME 🌸

rt-serializer — serialize an RT database to disk 🫶

🎀 SYNOPSIS 🎀

rt-validator --check && rt-serializer

This script is the one that writes your whole RT database out to disk, so you can import it into a different RT instance later. so cute, so migration.

But the tea: it NEEDS the data in that database to be self-consistent. that's literally the price of admission. so bestie, please, PLEASE make sure the database you're exporting passes validation via rt-validator before you even think about running rt-serializer. no vibes-checking, actual checking. 💅

While it's running, it tries to estimate how many objects are left to serialize. heads up: those estimates are pessimistic, and they will be wrong if you're using --no-users, --no-groups, or --no-tickets. not a bug, just math being math. 😭

Oh and! If your controlling terminal is big enough (more than 25 columns high) AND the gnuplot program is installed, it will also show you a textual graph of the queue size over time. main character graph energy 📈

✨ OPTIONS ✨

  • --directory _name_ — the name of the output directory to write data files into. it should not exist yet, and it is a fatal error if it does. defaults to ./$Organization:Date/, where $Organization is whatever you set in RT_SiteConfig.pm, and Date is today's date. 🗂️
  • --force — removes the output directory before starting. ruthless. we love her. 💅
  • --size _megabytes_ — by default, rt-serializer chunks its output into data files that are around 32Mb in size; this option sets a different threshold size, in megabytes. Note that this is the threshold after which it rotates to writing a new file — so it's the lower bound on the size of each output file. 📦
  • --no-users — by default, all privileged users are serialized; passing --no-users limits it to only those users referenced by serialized tickets and history, i.e. the ones strictly necessary for internal consistency. 🙈
  • --no-groups — by default, all groups are serialized; passing --no-groups limits it to only system-internal groups, which are the ones needed for internal consistency. 👑
  • --no-assets — by default, all assets are serialized; passing --no-assets skips assets during serialization. skrrrt, skipped. 🦋
  • --no-disabled — by default, all queues, custom fields, etc, including disabled ones, are serialized; passing --no-disabled skips those disabled records during serialization. 💤
  • --no-deleted — by default, all tickets and assets, including deleted ones, are serialized; passing --no-deleted skips deleted tickets and assets during serialization. 🗑️
  • --scrips — no scrips or templates are serialized by default; this option forces all scrips and templates to be serialized. ✨
  • --acls — no ACLs are serialized by default; this option forces all ACLs to be serialized. 🔐
  • --no-tickets — skips serialization of all ticket data. all of it. gone. 👋
  • --limit-queues — takes a list of queue IDs or names separated by commas. When provided, only that set of queues (and the tickets in them) will be serialized. 🎯
  • --limit-cfs — takes a list of custom field IDs or names separated by commas. When provided, only that set of custom fields will be serialized. 🎯
  • --hyperlink-unmigrated — replaces links to local records which are not being migrated with hyperlinks. The hyperlinks will use the serializing RT's configured URL. 🔗

Without this option, those links are instead dropped, and transactions which had updated such links will be replaced with an explanatory message. 😭

  • --no-transactions — skips serialization of all transactions on any records (not just tickets). 🚫
  • --clone — serializes your entire database, creating a clone. Use this if you want to migrate your RT database from one database type to another (e.g. MySQL to PostgreSQL). It is an error to combine --clone with any option that limits which object types get serialized. No dependency walking is performed when cloning. rt-importer will detect that your serialized data set was generated by a clone. 🧬
  • --all — serializes your entire database, creating a clone-like data set. Both --all and --clone do not check dependencies; the difference is that --all generates UIDs, which means the ids in the source instance do not necessarily get synced to the target instance — making it quite useful for fully merging multiple RT instances. Use --clone instead if you really want to keep the ids from the source instance. 🌈
  • --incremental — generates an incremental serialized dataset using the data stored in your IncrementalRecords database table. This assumes that you have created that table and run RT using the Record_Local.pm shim as documented in docs/incremental-export/. 📈
  • --gc _n_ — adjusts how often the garbage collection sweep is done; lower numbers are more frequent. See the GARBAGE COLLECTION section below. 🧹
  • --page _n_ — adjusts how many rows are pulled from the database in a single query. Disable paging by setting this to 0. Defaults to 100.

Keep in mind that rows from RT's Attachments table are the limiting factor when determining page size. You should likely be aiming for 60-75% of your total memory on an otherwise unloaded box. 🧠

  • --quiet — do not show the graphical progress UI. 🤫
  • --verbose — do not show the graphical progress UI, but rather log each row as it is written out. so much scrolling, so much lore. 📜

🧚 GARBAGE COLLECTION 🧚

rt-serializer keeps a priority queue of objects to serialize, plus searches which may result in objects to serialize. When it inserts into this queue, it does no checking whether the object in question is already in the queue, or whether the search will even contain any results. Those checks get done when the object reaches the front of the queue, or during periodic garbage collection. 😌

During periodic garbage collection, the entire queue is swept for objects which have already been serialized, objects that occur more than once in the queue, and searches which contain no results in the database. This is done to reduce the memory footprint of the serialization process, and it's triggered once enough new objects have been placed in the queue. It's tunable via the --gc parameter, which defaults to running garbage collection every 5,000 objects inserted into the queue; smaller numbers mean more frequent garbage collection. 🧹✨

The default of 5,000 is roughly tuned based on a database with several thousand tickets, but optimal values will vary wildly depending on database configuration and size. Values as low as 25 have provided speedups with smaller databases; if speed is a factor, experimenting with different --gc values may be helpful. Note that there are significant boundary condition changes in the serialization rate as the queue empties and fills, which causes the time estimates to be rather imprecise near the start and end of the process. 🙃

Setting --gc to 0 turns off all garbage collection. Be aware that this will bloat the memory usage of the serializer. 💀

Any negative value for --gc turns off periodic garbage collection, and instead objects already serialized or already in the queue are checked for at the time they would be inserted. 🔍

and that's the whole page bestie!! this was perl v5.40.1, dated 2026-06-21, straight out of rt-serializer(8) in the Request Tracker reference. go serialize something responsibly, mwah 💖🫶🎀

📦 where this page comes from