RT-SERIALIZER(1)

💖 RT-SERIALIZER(1) 💖

okay bestie, so this one lives in the User Contributed Perl Documentation section, and it's literally the tool that yeets your whole RT database onto disk so you can haul it over to a different RT instance later. 🌈

✨ NAME ✨

rt-serializer — serialize an RT database to disk. that's it, that's the whole vibe. 💅

---

🦋 SYNOPSIS 🦋

rt-validator --check && rt-serializer

so here's the tea: this script writes out your entire RT database to disk, for later import into a different RT instance. but — and this is the important part — it needs the data in your database to be self-consistent first. so before you even think about running rt-serializer, please make sure the database you're exporting passes validation by rt-validator. no cap. 🙏

while it's running, it'll try to estimate how many objects are left to serialize. heads up: those estimates are pessimistic, and they will be straight-up wrong if you're using --no-users, --no-groups, or --no-tickets. 😭

and if your controlling terminal is big enough (more than 25 columns high, bestie) and you've got the gnuplot program installed, it'll also show you a textual graph of the queue size over time. iconic. 📈✨

🌸 OPTIONS 🌸

• --directory name — the name of the output directory where the data files go. it should not exist yet, and if it does, that's a fatal error, periodt. defaults to ./$Organization:Date/, where $Organization is whatever you set in RT_SiteConfig.pm, and Date is today's date. 📁💖
• --force — nukes the output directory before it starts. 🔥
• --size megabytes — by default, rt-serializer chunks its output into data files of around 32Mb each. 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 literally the lower bound on the size of each output file. 📦
• --no-users — by default, all privileged users get serialized. passing --no-users limits it to only the users that are referenced by serialized tickets and history — y'know, the ones that are necessary for internal consistency. 🙈
• --no-groups — by default, all groups get serialized. passing --no-groups limits it to only system-internal groups, which are needed for internal consistency. 👯
• --no-assets — by default, all assets get serialized. passing --no-assets skips assets during serialization. ✂️
• --no-disabled — by default, all queues, custom fields, etc, including disabled ones, get serialized. passing --no-disabled skips those disabled records during serialization. 💤
• --no-deleted — by default, all tickets and assets, including deleted ones, get 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 — skip serialization of all ticket data. just… all of it. 🎫❌
• --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 that are not being migrated with actual hyperlinks. those hyperlinks will use the serializing RT's configured URL. 🔗

without this option, such links get dropped instead, and transactions that had updated such links get replaced with an explanatory message. lowkey tragic but that's the deal.

• --no-transactions — skip serialization of all transactions on any records (and yes, that means not just tickets). 🚫
• --clone — serializes your entire database, creating a clone. use this one 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 object types 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 clone-like data. both --all and --clone skip dependency checking, and the difference is that --all generates UIDs: meaning the ids in the source instance don't necessarily get synced to the target instance. which honestly makes it super useful for fully merging multiple RT instances. use --clone instead if you truly, genuinely want to keep the ids from the source instance. 🫶
• --incremental — will generate an incremental serialized dataset using the data stored in your IncrementalRecords database table. this assumes you've created that table and you've been running RT with the Record_Local.pm shim, as documented in docs/incremental-export/. 📚
• --gc n — adjust how often the garbage collection sweep is done; lower numbers are more frequent. see GARBAGE COLLECTION below. 🧹
• --page n — adjust how many rows get 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 you're determining page size. you should probably 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's written out. 🗣️📝

---

🎀 GARBAGE COLLECTION 🎀

okay so rt-serializer keeps a priority queue of objects to serialize, or searches that might result in objects to serialize. when it inserts into that 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 happen when the object reaches the front of the queue, or during periodic garbage collection. 🧠✨

during periodic garbage collection, the entire queue gets swept for objects that have already been serialized, objects that occur more than once in the queue, and searches that contain no results in the database. the point of all this is to reduce the memory footprint of the serialization process, and it gets triggered once enough new objects have been placed in the queue. this parameter is tunable with 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 your database configuration and size. values as low as 25 have provided speedups with smaller databases; so if speed is a factor for you, experimenting with different --gc values may genuinely be helpful. note that there are significant boundary condition changes in serialization rate as the queue empties and fills, which makes the time estimates 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 in the queue are checked for at the time they would be inserted. 💀

ngl bestie, --gc 0 and negative --gc values are your "please watch my RAM, I'm feeling reckless" options. proceed with main character energy but maybe also with top open in another terminal. 👀

---

so yeah, that's the whole page, mwah 💋 — written by the RT crew, shipped with perl v5.42.3, page dated 2026-07-20, and this manual page is literally just RT-SERIALIZER(1). go serialize something gorgeous. 💖✨🦋