Upgrading Solana Programs with the CLI

Hello! Welcome to the next lesson in our "Advanced Anchor and Program Lifecycle" module.

In the last lesson, we tackled a crucial aspect of program evolution: how to upgrade your on-chain data structures. We learned how to implement versioning and use Anchor's realloc constraint to perform "lazy migrations" on accounts, ensuring your program can handle data from different versions without breaking.

Today, we shift our focus from the data to the code. What happens when you need to fix a bug, add a new feature, or change the logic of an instruction? This lesson will teach you how to upgrade the deployed program logic itself using the Solana Command-Line Interface (CLI). This skill is fundamental to maintaining and improving your applications throughout their lifecycle.

The Upgrade Process: Surprisingly Simple

You might expect upgrading a live program on a blockchain to be a complex, multi-step ordeal. However, for Solana, the core process is remarkably straightforward. You use the exact same command for upgrading a program as you do for deploying it for the first time.

The key is that you are deploying the new program code to the same on-chain address, or Program ID. Your program's identity remains constant, but the underlying executable code is replaced.

Let's look at the official documentation to see the command.

As the documentation states, the workflow for an upgrade is:

1. Make changes to your program's Rust code.
2. Rebuild the program using anchor build (or cargo build-sbf for native programs).
3. Deploy the update using solana program deploy ./target/deploy/<YOUR_PROGRAM_NAME>.so.

The Solana CLI, when pointed at an existing Program ID that your wallet has upgrade authority over, will simply replace the old program executable with the new one.

Handling Program Size Increases

In our last lesson, we saw that we had to use realloc to increase the size of a data account. What happens if our program account needs to grow? For example, adding a new instruction or complex logic will increase the size of the compiled .so file.

The ProgramData account, which stores your program's executable code, is allocated with a specific amount of space on the blockchain. By default, this is double the size of your initial program, giving you room for future upgrades.

But what if your upgrades exceed that initial buffer?

As noted in the documentation you just read, the solana program deploy command is smart. If it detects that the new program binary is larger than the currently allocated space, it will automatically attempt to increase the size of the ProgramData account and charge your wallet for the additional rent required.

However, sometimes you might want or need to manage this process more explicitly. Let's watch a video that touches on this scenario.

The video brings up an important distinction:

• Upgrading Code vs. Changing Data Structures: The instructor correctly points out a major caveat. A simple program code upgrade (what we are focusing on) is straightforward. However, if you fundamentally change an existing account's data layout without a migration strategy (like we learned in the last lesson), a simple code upgrade will fail at runtime. In his specific case, he chose to deploy a completely new program. For our purposes, we assume we've handled data migration correctly and are only concerned with the code and its size.

The key takeaway from the video is the manual alternative to the automatic resizing: the solana program extend command.

If an automatic upgrade fails, or if you want to pre-allocate space as part of a script, you can use:
solana program extend <PROGRAM_ID> <ADDITIONAL_BYTES>

This command increases the data size of the program account, funding the additional rent from your wallet. After extending the account, you can then run solana program deploy successfully.

A Practical Upgrade Workflow

Let's formalize the steps for a well-managed program upgrade on devnet.

1. Check Current State: First, get the details of your deployed program. Find your program ID (you can get it from Anchor.toml or by running anchor keys list).

   solana program show <YOUR_PROGRAM_ID> --url devnet
   

   Note the Data Length value. This is the total space (in bytes) allocated for your program's executable.

2. Make Code Changes & Rebuild: Modify your program logic in src/lib.rs. For a simple test, you could change the text in a msg! macro. Then, rebuild.

   anchor build
   

3. Check New Program Size: Compare the old size with the new.

   wc -c < ./target/deploy/<YOUR_PROGRAM_NAME>.so
   

   If this new size is greater than the Data Length from Step 1, you know the program account will need to be resized.

4. Deploy the Upgrade: Run the deploy command, pointing to the devnet cluster. Anchor's deploy command is a convenient wrapper that does this for you.

   # Ensure your Anchor.toml is set to the devnet cluster and your program ID
   # [provider]
   # cluster = "devnet"
   #
   # [programs.devnet]
   # my_program = "YOUR_PROGRAM_ID"
   
   anchor deploy
   

   Alternatively, using the Solana CLI directly:

   solana program deploy target/deploy/<YOUR_PROGRAM_NAME>.so --url devnet
   

5. Verify the Upgrade: Check the program details again.

   solana program show <YOUR_PROGRAM_ID> --url devnet
   

   You should see that the Last Deployed In Slot has increased, and if the program grew, the Data Length and Balance (due to rent) will have changed. Your upgrade is now live.

Advanced Upgrades: Using a Buffer Account

For high-stakes upgrades, especially on mainnet, deploying directly into the program account can be risky. If the deployment fails midway, you could be left in an inconsistent state. A more robust and secure pattern involves using an intermediate buffer account.

This process separates the uploading of the new code from the actual activation of that code.

The buffer workflow looks like this:

1. Write to Buffer: Instead of deploying directly, you upload the new program binary to a new, temporary buffer account.
   solana program write-buffer ./target/deploy/program.so
2. Verify (Optional but Recommended): The authority (e.g., a multi-signature wallet or DAO) can now inspect the bytecode in this buffer account on-chain to verify it matches the intended, audited source code. This is a critical security step.
3. Upgrade from Buffer: Once verified, the upgrade authority issues the command to upgrade the program using the data from the buffer.
   solana program deploy --buffer <BUFFER_ADDRESS>

This two-step process provides a crucial airlock. It allows for off-chain verification and governance to happen before the new code goes live, which is essential for secure program lifecycle management.

Conclusion

You now understand the mechanics of upgrading Solana program code. While the basic command is simple, the concepts of account size, rent, and advanced buffer-based workflows are essential for professional development.

Key Takeaways:

• Upgrading a program is done with the same solana program deploy command used for the initial deployment.
• The Program ID remains constant, preserving your program's address.
• The CLI will attempt to automatically resize the program account if the new code is larger, but you can do it manually with solana program extend.
• For secure, mission-critical upgrades, a two-step process using an intermediary buffer account is the recommended best practice.

Preview of the Next Lesson

We've discussed upgrading and mentioned "upgrade authority" several times. But what is this authority? Who holds it, and can it be changed? In our next lesson, we will dive deep into managing the upgrade authority of a deployed program, including how to transfer it and how to make a program permanently immutable.