What can I do with export/import?
- Export/import data to/from GoogleSheets or Excel in Unity Editor (during game development)
- Export/import data from/to Excel file at runtime (from builds, PC/Mac/Linux only) with this plugin. Optional excel file monitor, which auto-import data on file change, is also available.
- Excel file monitor, which auto-import excel data in Unity Editor, can be downloaded here
- Update database data on players devices at runtime from GoogleSheets with LiveUpdate plugin
- Currently there is no way to write to GoogleSheets at runtime from players devices (Why not?)
- 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.
General ideaHere is the illustration about how BGDatabase data is mapped to spreadsheets.
Setup guide for export/import
- Create a datasource for Excel/GoogleSheets
- Create a job
- [Optional] Choose tables/fields you want to export/import
Export does not require any additional steps, but if you want to import data from external datasource for the first time, you need to ensure the data has a proper layout (as described in "General idea" section), e.g. your sheets has the same name as your database tables and the first row has field names.
[Optionally] Also, if you want to create a link between your external data rows and database rows, you need to add _id column to your data and ensure a job's "Update ids on import" parameter is toggled on.
Using merge settings
You have full control over which data you want to synchronize: you can add, delete, update and you can choose 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:
- Matching rows : they exists in the Source and in the Destination. Can be updated and you can choose which fields to update.
- Missing rows : they exists only in the Source. Can be added to Destination.
- 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
Names mapping config
By default naming convention is used to map sheets to tables and columns to fields. It can be overridden with names mapping config, which allows to use any names for sheets and columns and map them to tables/fields. Names mapping config is available for every data source and is used while importing/exporting from Unity Editor
|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|
||Callbacks to be called before after merging. Return true from OnBeforeMerge to cancel merging|
||Callbacks to be called before deleting the row. Return true to cancel removal.|
||Callbacks to be called before adding the row. Return true to cancel adding.|
||Callbacks to be called before updating the row. Return true to cancel updating.|
Callbacks to be called before updating the row' field. The same as
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
We use Vertical bar (Pipe) symbol
| to separate values of the list, for example List<bool> is
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 choose 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. If your app/game is running on a single device, use this plug-in
LONG READ: We believe giving direct write GoogleSheets access to multiple player devices does not make much sense, due to the following reasons:
- 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.
- 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
- 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:
- 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. Also, read our mini tutorial, how to use Google Forms to update GoogleSheets here
- If you need more sophisticated control GoogleSheets dotnet API library v4 is probably the best starting point.