Export Import

What can I do with export/import?

  1. Export/import any data to/from GoogleSheets/Excel in Editor (during game development)
  2. Monitor excel file and auto-import data in Editor and at runtime (from builds) with our extension packages, which can be downloaded here (PC/Mac/Linux only)
  3. Update database data on players devices at runtime from GoogleSheets with LiveUpdate plugin
  4. Currently there is no way to write to GoogleSheets at runtime from players devices (Why not?)
  5. Backup/restore database in json format in Editor


You can edit database data in external tools, such as Excel/Open Office/Libre Office or Google Sheets.

BG Database supports export/import to/from Excel files (xls and xlsx), Google Sheets and json (backup only).

Full import/export works in Editor only, but you can update database data on players devices from GoogleSheets with LiveUpdate addon. No way to update GoogleSheets data from players devices yet.

Use json export/import to create full database backup.

This article describes common procedure and ideas, common for both Excel and Google Sheets. You can find provider' specific instruction here: for Excel/Open Office, for Google Sheets

General idea

Here is the illustration about how BGDatabase data is mapped to spreadsheets.

Using merge settings

You have full control over which data you want to synchronize: you can add, delete, update and you can chose which fields you wish to update.

Here is how it works: Every synchronization has a source and a destination. If you are exporting data from BDDatabase to, let's say, Excel file- the source is BGDatabase and a destination- is Excel file. Here is how data is classified during syncing:

So, there are 3 types of rows during syncing:

  1. Matching rows : they exists in the Source and in the Destination. Can be updated and you can chose which fields to update.
  2. Missing rows : they exists only in the Source. Can be added to Destination.
  3. Orphaned rows : they exists only in the Destination. Can be removed from Destination.

Let's look at merge settings and find out how we can define actions to take during syncing

Additional parameters

Name Description
Update Ids on import If you are adding new rows in external tools, leave _id column empty and enable this parameter. Id values from database will be transferred to _id column when you import new rows.
Transfer rows order Rows order from the source will be transferred to the destination. Import/export and Excel/GoogleSheets are all supported.

Running Export/Import for the first time

To be able to sync with BGDatabase, you need a corresponding structure created in Excel/GoogleSheets, e.g. you need sheets, named after your tables names and header columns, named after you field names (as described above in "General idea" section).

You can easily create this structure by exporting your data to the empty spreadsheet/xls file

  • Make sure to target empty spreadsheet/xls file
  • Make sure to include all tables/fields you want to export in the settings. Included tables/fields will be highlighted in green
  • Make sure all tables you want to include have "Add missing rows" toggle turned on.(cause all the rows will be "missing rows" when you export to empty spreadsheet)
  • Export data once- all required structure will be created for you

Row-level control for merge settings

Merge settings let you configure which table/fields you want to add/delete/update, but it does not give you the opportunity to define which rows you want to add/delete/update

For row-level control, you can implement C# controller class, which can cancel any operation if some condition is met. This is how:

  • Create your own C# class with unique name, set this class name to "Controller Type" field of merge settings (using the full name with namespace).
  • Implement any number of interfaces (namespace is BansheeGz.BGDatabase, interfaces defined inside class BGMergeSettingsEntity), listed below to receive callback method invocations. Return true from this methods to cancel operation
Interface type method(s) to implement description
IMergeReceiver public bool OnBeforeMerge(BGRepo from, BGRepo to)
public void OnAfterMerge(BGRepo @from, BGRepo to)
Callbacks to be called before after merging. Return true from OnBeforeMerge to cancel merging
IRemoveOrphanedReceiver public bool OnBeforeDelete(BGEntity toEntity) Callbacks to be called before deleting the row. Return true to cancel removal.
IAddMissingReceiver public bool OnBeforeAdd(BGEntity fromEntity) Callbacks to be called before adding the row. Return true to cancel adding.
IUpdateMatchingReceiver public bool OnBeforeUpdate(BGEntity @from, BGEntity to) Callbacks to be called before updating the row. Return true to cancel updating.
IUpdateMatchingFieldReceiver public bool OnBeforeFieldUpdate(BGField fromField, BGField toField, BGEntity @from, BGEntity to) Callbacks to be called before updating the row' field. The same as IUpdateMatchingReceiver, but it's called on per field basis. IUpdateMatchingReceiver is called before this callback, and if IUpdateMatchingReceiver return true, this callback will never be invoked (cause updating entity will be cancelled by IUpdateMatchingReceiver)

You can find an example of such controller class on Save/Load addon page.

Default field value string format

We use Acute (Back quote) symbol ` to separate tokens of single value, for example Vector3.zero is 0`0`0

We use Vertical bar (Pipe) symbol | to separate values of the list, for example List<bool> is 0|1|0

Custom field value string format

Most of the fields support custom string format (except for Unity assets and relations). You can create your own class, implementing BGStringFormatter<T> interface (T is a field value type) and assign it under "M" menu as a custom string value formatter

Adding rows in external tools

Each row has it's own id- 22 symbols string. It's computer-generated value, based on Guid generation.

While creating rows in external tool, you can leave it blank, and it will be updated during importing procedure (make sure you toggled "Update Ids on Import" on)

Creating database backup in json format

Exporting data to json allows you to create a full database backup in human readable form as json file. With json you can not chose which data you want to be exported/imported, full data including database structure will be included.

You can use this backup later to fully restore the database (including structure)

Tables naming restriction

If you plan to use Excel/GoogleSheets, avoid giving your tables similar names with only difference in lower/upper letter(s) (like "test" "Test", "tESt" etc.). It will work fine with BGDatabase, however both Excel and GoogleSheets consider such names to be equal, and it will result in errors when you try to export the data.

Why you do not provide an option to update GoogleSheets data from player devices?

TLDR: Our export procedure is not meant to be executed simultaneously by multiple clients

LONG READ: We believe giving direct write GoogleSheets access to player devices does not make much sense, due to the following reasons:

  1. Durability problem: this is the main reason- there is no way to make sure some change will not erase previous change. Let's say you want to store the number of times your app was launched. So you read cell value, you increase it by 1 and you write it back. But if 10 players launch your game simultaneously, they all read initial zero value from GoogleSheets, increase it by one and write it back, so the final value will be 1, not 10. This problem apply to any shared data.
  2. Security problem: giving write access means giving credentials to change data, and there is no way to make sure these credentials will not be hacked
  3. Performance problem: GoogleSheets is not fast enough to be used as online database for big amount of users. Many tasks will require to read data first before updating, and it can take a lot of time. Also there is 2 million cells max restriction.

All this problems can be solved with a proxy server, but it also means there is no need for direct access to GoogleSheets.

If you are still looking for a way to write data to GoogleSheets from players devices:

  1. If all you need is to add data to spreadsheet, you can use Google Forms, linked to a spreadsheet and HTTP POST to add data to spreadsheet
  2. If you need more sophisticated control GoogleSheets dotnet API library v4 is probably the best starting point.

What's next?

Read product specific guides next
  1. Excel/Open Office
  2. Google Sheets