Extension:Cargo/recreating tables

## Introduction

### What?

Recreating a Cargo table is the process of deleting the current version of a table and replacing it with a new, updated version. This process is generally broken into two separate phases; first, the new table is created, and then the old one is deleted; see replacement tables for more information.

### Why?

Cargo tables need to be recreated any time the declaration of the table is modified, with a field added or removed, or having its type changed. Tables can also be recreated to speed up the propagation of updated data to the table, since a recreation is typically significantly faster than a set of blank edits on the pages in question.

### Who?

To recreate a Cargo table, you need to have the right `recreatecargodata`. By default, this right is granted to Bureaucrats/Administrators and Wiki Representatives/Specialists. If you need a table recreated and don't have this right, you should talk to your Wiki Guardian or Manager.

### How?

To recreate a table, go to the *declaring* template and click "Recreate data" in the upper-right corner of the page. You can also recreate tables via the Special:CargoTables interface. To switch in a replacement table, use the interface at Special:CargoTables; there will be a clickable link that says Switch to using this table. for the table you need to switch.

## Replacement tables

Replacement tables should almost always be used. The only case in which you may not want to use one is when your table currently isn't in use anywhere. When you use a replacement table to recreate, the wiki sets the original version of the table as read-only, in other words unable to be changed. This ensures that the wiki doesn't "break" during the process of repopulating the new version of the table. Once the table has finished repopulating, you can switch it in. While a table is repopulating, a message will say `**Note:** One or more of these tables are currently being populated, via the job queue.` at the top of Special:CargoTables (only on the overview page, not on the individual table page). Once this message goes away, you know that the recreation has finished, and it's safe to switch to the new version of the table.

### Warnings

* Do not switch a replacement table in before it finishes repopulating, this can cause problems with the recreation.
* Do not delete a replacement table while it is still repopulating. It's fine to delete a replacement table after it's done repopulating, though, if you decide you don't actually want it.
* The fields in the replacement table aren't available to queries until *after* it's switched in, so if you save changes to templates that use your new fields before it's switched in, you might cause errors.

## Best practices

This section outlines best practices that will ensure stable recreations and if you use a lot of Cargo. Even if you currently don't have much Cargo, it's not a bad idea to get started with setups like this early. That said, if anything here feels confusing or like too much trouble to be worth it, and none of your tables has more than about 2000 rows, it's probably safe to ignore most things here.

### Segregating declaration

If possible, your Cargo declarations should be kept separate from any templates that are actually used in pages. There are a few reasons for this:

* When you recreate a table to add a field, you will have to edit the declaration template. If the declaring template is transcluded in a lot of pages, then a lot of jobs will be created (in other words, the server will get really busy). Pre-existing jobs can slow down or even interfere with the Cargo recreation jobs.
* This convention gives you a consistent naming scheme for your declaring templates (such as `Template:TableName/CargoDec`) so that they can be inferred by i18n templates etc and linked to for easy editing.
	+ You can also take advantage of consistent naming schema when creating "search engines" or bookmarklets in your browser with `%s` to easily navigate to your declarations.
* When you have more complicated templates that store to multiple tables, you wouldn't be able to declare all of the tables in the same template anyway. Using this convention from the start will save you headache later on when you'd be forced into a scenario of having inconsistent conventions.
* Similarly, if you write Lua code, your declarations will be separate from your stores; you may as well have a proscribed convention for locating your declarations.

### Avoid major template edits before or during a recreation

Any template, no matter how simple, that's transcluded in a large number of wiki pages, will have a negative impact on wiki performance every time you edit it. Of course, sometimes you will need to edit such high-use templates, but it's best to time those edits away from when you are recreating Cargo tables. What if you need to edit the template that's storing data? Use one of the following workflows if possible:

1. Add new fields to segregated Declaration template
2. Recreate table
3. Edit storing template to support new data
4. Populate new data

Or, if the new fields are based on existing data:

1. Add new fields to segregated Declaration template
2. Recreate table
3. Edit storing template to support new fields
4. Wait for job queue to reach zero
5. Recreate the table again

These procedures may sound convoluted, but in the long run you'll save a lot of time that you'd otherwise have to spend waiting for recreates or running blank edits.

## General issues

* Even though the interface suggests you can, you can't actually recreate a table from a template that attaches it. Navigate to the declaring template first, and then recreate from there.