VistaDB 5
Gibraltar VistaDB > Getting Started > Getting Started - Upgrading to VistaDB 5.2
Getting Started - Upgrading to VistaDB 5.2

If you're using VistaDB 3.x or 4.x, just walk through the following items to upgrade your application to VistaDB 5. 

If you are using VistaDB 5.0, jump to step 3 for information on upgrading the file format of your database.

 Step 1: Change References

You will need to remove references in your application to the older VistaDB libraries and replace them with the appropriate updated reference:

If You Referenced... Replace it with...
VistaDB.5.NET40.dll (for projects targeting .NET 4.0 or later)
VistaDB.5.NET20.dll (for projects targeting older versions of .NET)
VistaDB.Entity.4.dll VistaDB.5.Entities.4.0.NET40.dll

At this point your project may not compile if you are using Typed DataSets or have certain application configuration entries.

Upgrading Entity Framework

If you have been using Entity Framework you are likely planning two upgrades - one for Entity Framework and one for VistaDB.  We recommend you first upgrade VistaDB to VistaDB 5 while keeping Entity Framework the same and then upgrade to Entity Framework 6 (or later) following our

Updating Typed DataSets

If you previously used the Visual Studio DataSet designer to create DataSets for your data access using VistaDB 4 you will need to edit them using the Xml editor in Visual Studio to update their reference.  For details see How To - Update Datasets to use VistaDB 5.

 Step 2: Changing Connection Strings and Application Configuration

Your application or web site should have a configuration file entry for the VistaDB data provider.  You'll need to update this to point to the new assembly so that ADO.NET can find it at runtime.  You can generally search for any reference to "VistaDB.4" or "VistaDB.NET20" (depending on the version you're upgrading from) and change the assembly name to the assembly you selected in Step 1.  In the end you want it to look like this:

<?xml version="1.0" encoding="utf-8"?>
    <add name="YourAppConnection" 
         connectionString="Data Source=YourAppDatabase.vdb5;Open Mode=NonExclusiveReadWrite" 
         providerName="System.Data.VistaDB5" />
      <remove invariant="System.Data.VistaDB5" />
      <add invariant="System.Data.VistaDB5" name="VistaDB 5 Data Provider"
           type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.5.NET40" />

The most important change is in the line that adds the new DbProviderFactory - the type needs to be set to refer to refer to the new engine assembly.

If you are using VistaDB.5.NET40 (recommended for .NET 4.0 and later applications) use this DbProviderFactory setting:

<add invariant="System.Data.VistaDB5" name="VistaDB 5 Data Provider" 
      type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.5.NET40" />

If you are using VistaDB.5.NET20 (for supporting .NET 2.0 - .NET 3.5 applications) use this DbProviderFactory setting:

<add invariant="System.Data.VistaDB5" name="VistaDB 5 Data Provider" 
      type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.5.NET20" />

In the above example the provider name is set to the default used for VistaDB 5 (System.Data.VistaDB5) but this can be anything in your application as long as you use the same value in the connection string and in the DbProviderFactories invariant name.

Why does the configuration example first remove the provider factory? On any computer where VistaDB 5 has been installed the provider factory is already registered in the machine.config file so it will be present.  This is necessary for the VistaDB Visual Studio designer to work but isn't a recommended deployment configuration.  Therefore, the system-wide setting has to be removed for your application to add its own setting.  Otherwise your application will fail on your development box (but will work when deployed)

For more information on how to configure your connection in your application configuration file, see ADO.NET Factory Objects in your app.config or web.config.

 Step 3: Upgrading your Database

VistaDB 5.1 has a new database file format compared to both VistaDB 5.0 and older versions of VistaDB.  While the VistaDB 5.* engines can continue to read older formats, they need the database to be upgraded to at least the VistaDB 5.0 file format before they can do any updates.  Upgrading a database is as simple as packing it using either the API or Data Builder.  If your database is using the .vdb4 extension (the default) for VistaDB 4 then you'll want to rename it to .vdb5 as well so double-clicking it will open Data Builder. 

  • If your Database is in VistaDB 5.1 Format: No upgrade is required, the same format is used in version 5.5.
  • If your Database is in VistaDB 5.0 Format: You can read and write it with VistaDB 5.1 and alter.  Some of the new performance features will not be available until it is upgraded.
  • If your Database is in VistaDB 3 or 4 Format: You can only open it in read-only mode until it is upgraded.

If you have your database in your Visual Studio project we recommend renaming it to change the file extension then double-clicking it to open it in Data Builder.  You can then upgrade it from Data Builder.

Be sure to update your connection string and other places you reference the file extension in your application

 Step 4: Deploying Your Upgrade

When deploying your updated application, you will need to handle upgrading the deployed database.  The best way to do this is to use the VistaDB API to Pack the database.   You may want to follow a process similar to this:

  1. Detect an old database by checking that the data file has the extension .vdb4 and there isn't a corresponding file with the extension .vdb5
  2. Upgrade the database using the Pack API.  Rename the database file after the Pack has successfully completed.  This is a good scenario to use the backup option where a backup copy is made during the upgrade.  For more information, see How To - Pack a Database.
  3. Update the stored connection information to refer to the new file name with the new extension
See Also