| Name | backup-airtable JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Quickly and painlessly dump all your Airtable schemas & data to JSON. |
| upload_time | 2025-02-23 07:34:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
airtable
backup
exporter
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# backup-airtable
Export your [Airtable](https://airtable.com/) data to JSON files. It exports both the table's schema and the records.
## Installation
The easiest way to run this is using [pipx](https://pypa.github.io/pipx/):
```shell
pipx install backup-airtable
```
You can also use brew:
```shell
brew install xavdid/projects/backup-airtable
```
## Usage
Once [authenticated](#authentication), running `backup-airtable` will immediately start downloading data. There are a few available options (viewable via `backup-airtable --help`):
```
Usage: backup-airtable [OPTIONS] [BACKUP_DIRECTORY]
Save data from Airtable to a series of local JSON files / folders
Options:
--version Show the version and exit.
--ignore-table TEXT Table id(s) to ignore when backing up.
--airtable-token TEXT Airtable Access Token [required]
--include-comments Whether to include row comments in the backup. May
slow down the backup considerably if many rows have
backups.
--help Show this message and exit.
```
You'll likely only need `ignore-table` (which you can specify multiple times) to ignore specific tables from bases you otherwise want to include.
### Examples
- `backup-airtable`
- `backup-airtable --include-comments`
- `backup-airtable some_backup_folder`
- `backup_airtable --ignore-table tbl123 --ignore-table tbl456`
## Authentication
You need to create a [personal access token](https://airtable.com/developers/web/guides/personal-access-tokens) to use this tool. It has the format `pat123.456`. They can be created at https://airtable.com/create/tokens.
Ensure it has the following scopes:
- `data.records:read`
- `schema.bases:read`
- if you're going to export comments (see [comments](#comments)):
- `data.recordComments:read`
You can give it access to as many or as few bases as you'd like. Everything the token has access to will be backed up.
### Supplying the Key
You can make the key available in the environment as `AIRTABLE_TOKEN` or via the `--airtable-token` flag:
- `AIRTABLE_TOKEN=pat123.456 backup-airtable`
- `backup-airtable --airtable-token pat123.456`
## Exported Data Format
This tool creates folders for each base, each containing `records.json` and `schema.json`:
```
. (backup_directory)
├── videogames/
│ ├── games/
│ │ ├── schema.json
│ │ └── records.json
│ └── playthroughs/
│ ├── schema.json
│ └── records.json
└── tv/
├── shows/
│ ├── schema.json
│ └── records.json
├── seasons/
│ ├── schema.json
│ └── records.json
└── watches/
├── schema.json
└── records.json
```
The contents of each file is the raw API response for [the table's schema](https://airtable.com/developers/web/api/get-base-schema) (which includes formula definitions):
```json
{
"fields": [
{
"id": "fldAReWzcSCy8lR6S",
"name": "Name",
"type": "singleLineText"
},
{
"id": "fldapjPtWVGLeVEz6",
"name": "Style",
"options": {
"choices": [
{
"color": "redLight2",
"id": "selpGtES7bVHWFO68",
"name": "Competitive"
},
{
"color": "blueLight2",
"id": "sel176WltZzGmNl3l",
"name": "Cooperative"
}
]
},
"type": "singleSelect"
},
{
"id": "fldpMVjIrO1QjFeAy",
"name": "Is Available?",
"options": {
"formula": "AND(IF({fldGC6t3qWTFCESvA}, {fldGC6t3qWTFCESvA}<={fld4hmOueoB5ah8Io}, 1), {fld4gls5vBed7NBOP} = 0)",
"isValid": true,
"referencedFieldIds": [
"fldGC6t3qWTFCESvA",
"fld4hmOueoB5ah8Io",
"fld4gls5vBed7NBOP"
],
"result": {
"options": {
"precision": 0
},
"type": "number"
}
},
"type": "formula"
}
],
"id": "tblvcNVpUk07pRxUQ",
"name": "Games",
"primaryFieldId": "fldAReWzcSCy8lR6S",
"views": [
{
"id": "viw2PrDfjQquMoTKb",
"name": "Main View",
"type": "grid"
},
{
"id": "viweVcA0peE3M3zag",
"name": "Add a New Game",
"type": "form"
}
]
}
```
and the [records themselves](https://airtable.com/developers/web/api/list-records):
```json
[
{
"commentCount": 0,
"createdTime": "2017-09-19T06:21:48.000Z",
"fields": {
"Name": "Libertalia: Winds of Galecrest",
"Style": "Competitive",
"Is Available?": 1
},
"id": "rec0wIiSnMutUfoTY"
},
{
"commentCount": 0,
"createdTime": "2023-09-19T06:20:20.000Z",
"fields": {
"Name": "Hanabi",
"Style": "Cooperative",
"Is Available?": 0
},
"id": "rec48RFqGw8hAmZFY"
}
]
```
### Comments
Each row in Airtable can have comments, but downloading them takes an extra API call _per row_. For bases with lots of rows with comments, this can dramatically slow down the backup.
Comments will be included, oldest to newest, on each row:
```json
{
"commentCount": 1,
"comments": [
{
"author": {
"email": "email@website.com",
"id": "usrOrn2etJhbw2dem",
"name": "Bruce Wayne"
},
"createdTime": "2025-02-21T08:05:25.000Z",
"id": "comx1KUhmPiHYX10w",
"lastUpdatedTime": null,
"text": "cool comment!"
}
],
"createdTime": "2021-05-24T04:19:13.000Z",
"fields": {
"Name": "Vantage",
"Style": "Cooperative",
"Is Available?": 0
},
"id": "recKPmZ4DkjYyFrV4"
},
```
## Differences from Upstream
This was originally forked from [simonw/airtable-export](https://github.com/simonw/airtable-export) and has since diverged. In the interest of simplicity & my own needs, I:
- made `backup_directory` optional; it defaults to `./airtable-backup-<ISO_DATE>`
- removed `ndjson`, `yaml`, and `sqlite` options; it always outputs formatted JSON
- removed `base_id`; it pulls every base the auth token has access to
- removed `user-agent` option for simplicity (though would be open to re-adding it later, if needed). It makes calls as default of `backup-airtable`
- removed `schema` option; it always dumps the schema
- removed `http-read-timeout`; it defaults to a high-enough value of 60 seconds
- it doesn't flatten the record. the top level keys are `id`, `createdTime`, and `fields`
## Development
This project uses [just](https://github.com/casey/just) for running tasks. First, create a virtualenv:
```shell
python -m venv .venv
source .venv/bin/activate
```
Then run `just install` to install the project and its development dependencies. At that point, the `backup-airtable` will be available. Run `just` to see all the available commands.
Raw data
{
"_id": null,
"home_page": null,
"name": "backup-airtable",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "airtable, backup, exporter",
"author": null,
"author_email": "David Brownman <beamneocube@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c1/fd/f824ad11e89959762bb70e603406ce8f44bf6c3dfa1e66872910bcb65769/backup_airtable-0.2.0.tar.gz",
"platform": null,
"description": "# backup-airtable\n\nExport your [Airtable](https://airtable.com/) data to JSON files. It exports both the table's schema and the records.\n\n## Installation\n\nThe easiest way to run this is using [pipx](https://pypa.github.io/pipx/):\n\n```shell\npipx install backup-airtable\n```\n\nYou can also use brew:\n\n```shell\nbrew install xavdid/projects/backup-airtable\n```\n\n## Usage\n\nOnce [authenticated](#authentication), running `backup-airtable` will immediately start downloading data. There are a few available options (viewable via `backup-airtable --help`):\n\n```\nUsage: backup-airtable [OPTIONS] [BACKUP_DIRECTORY]\n\n Save data from Airtable to a series of local JSON files / folders\n\nOptions:\n --version Show the version and exit.\n --ignore-table TEXT Table id(s) to ignore when backing up.\n --airtable-token TEXT Airtable Access Token [required]\n --include-comments Whether to include row comments in the backup. May\n slow down the backup considerably if many rows have\n backups.\n --help Show this message and exit.\n```\n\nYou'll likely only need `ignore-table` (which you can specify multiple times) to ignore specific tables from bases you otherwise want to include.\n\n### Examples\n\n- `backup-airtable`\n- `backup-airtable --include-comments`\n- `backup-airtable some_backup_folder`\n- `backup_airtable --ignore-table tbl123 --ignore-table tbl456`\n\n## Authentication\n\nYou need to create a [personal access token](https://airtable.com/developers/web/guides/personal-access-tokens) to use this tool. It has the format `pat123.456`. They can be created at https://airtable.com/create/tokens.\n\nEnsure it has the following scopes:\n\n- `data.records:read`\n- `schema.bases:read`\n- if you're going to export comments (see [comments](#comments)):\n - `data.recordComments:read`\n\nYou can give it access to as many or as few bases as you'd like. Everything the token has access to will be backed up.\n\n### Supplying the Key\n\nYou can make the key available in the environment as `AIRTABLE_TOKEN` or via the `--airtable-token` flag:\n\n- `AIRTABLE_TOKEN=pat123.456 backup-airtable`\n- `backup-airtable --airtable-token pat123.456`\n\n## Exported Data Format\n\nThis tool creates folders for each base, each containing `records.json` and `schema.json`:\n\n```\n. (backup_directory)\n\u251c\u2500\u2500 videogames/\n\u2502 \u251c\u2500\u2500 games/\n\u2502 \u2502 \u251c\u2500\u2500 schema.json\n\u2502 \u2502 \u2514\u2500\u2500 records.json\n\u2502 \u2514\u2500\u2500 playthroughs/\n\u2502 \u251c\u2500\u2500 schema.json\n\u2502 \u2514\u2500\u2500 records.json\n\u2514\u2500\u2500 tv/\n \u251c\u2500\u2500 shows/\n \u2502 \u251c\u2500\u2500 schema.json\n \u2502 \u2514\u2500\u2500 records.json\n \u251c\u2500\u2500 seasons/\n \u2502 \u251c\u2500\u2500 schema.json\n \u2502 \u2514\u2500\u2500 records.json\n \u2514\u2500\u2500 watches/\n \u251c\u2500\u2500 schema.json\n \u2514\u2500\u2500 records.json\n```\n\nThe contents of each file is the raw API response for [the table's schema](https://airtable.com/developers/web/api/get-base-schema) (which includes formula definitions):\n\n```json\n{\n \"fields\": [\n {\n \"id\": \"fldAReWzcSCy8lR6S\",\n \"name\": \"Name\",\n \"type\": \"singleLineText\"\n },\n {\n \"id\": \"fldapjPtWVGLeVEz6\",\n \"name\": \"Style\",\n \"options\": {\n \"choices\": [\n {\n \"color\": \"redLight2\",\n \"id\": \"selpGtES7bVHWFO68\",\n \"name\": \"Competitive\"\n },\n {\n \"color\": \"blueLight2\",\n \"id\": \"sel176WltZzGmNl3l\",\n \"name\": \"Cooperative\"\n }\n ]\n },\n \"type\": \"singleSelect\"\n },\n {\n \"id\": \"fldpMVjIrO1QjFeAy\",\n \"name\": \"Is Available?\",\n \"options\": {\n \"formula\": \"AND(IF({fldGC6t3qWTFCESvA}, {fldGC6t3qWTFCESvA}<={fld4hmOueoB5ah8Io}, 1), {fld4gls5vBed7NBOP} = 0)\",\n \"isValid\": true,\n \"referencedFieldIds\": [\n \"fldGC6t3qWTFCESvA\",\n \"fld4hmOueoB5ah8Io\",\n \"fld4gls5vBed7NBOP\"\n ],\n \"result\": {\n \"options\": {\n \"precision\": 0\n },\n \"type\": \"number\"\n }\n },\n \"type\": \"formula\"\n }\n ],\n \"id\": \"tblvcNVpUk07pRxUQ\",\n \"name\": \"Games\",\n \"primaryFieldId\": \"fldAReWzcSCy8lR6S\",\n \"views\": [\n {\n \"id\": \"viw2PrDfjQquMoTKb\",\n \"name\": \"Main View\",\n \"type\": \"grid\"\n },\n {\n \"id\": \"viweVcA0peE3M3zag\",\n \"name\": \"Add a New Game\",\n \"type\": \"form\"\n }\n ]\n}\n```\n\nand the [records themselves](https://airtable.com/developers/web/api/list-records):\n\n```json\n[\n {\n \"commentCount\": 0,\n \"createdTime\": \"2017-09-19T06:21:48.000Z\",\n \"fields\": {\n \"Name\": \"Libertalia: Winds of Galecrest\",\n \"Style\": \"Competitive\",\n \"Is Available?\": 1\n },\n \"id\": \"rec0wIiSnMutUfoTY\"\n },\n {\n \"commentCount\": 0,\n \"createdTime\": \"2023-09-19T06:20:20.000Z\",\n \"fields\": {\n \"Name\": \"Hanabi\",\n \"Style\": \"Cooperative\",\n \"Is Available?\": 0\n },\n \"id\": \"rec48RFqGw8hAmZFY\"\n }\n]\n```\n\n### Comments\n\nEach row in Airtable can have comments, but downloading them takes an extra API call _per row_. For bases with lots of rows with comments, this can dramatically slow down the backup.\n\nComments will be included, oldest to newest, on each row:\n\n```json\n {\n \"commentCount\": 1,\n \"comments\": [\n {\n \"author\": {\n \"email\": \"email@website.com\",\n \"id\": \"usrOrn2etJhbw2dem\",\n \"name\": \"Bruce Wayne\"\n },\n \"createdTime\": \"2025-02-21T08:05:25.000Z\",\n \"id\": \"comx1KUhmPiHYX10w\",\n \"lastUpdatedTime\": null,\n \"text\": \"cool comment!\"\n }\n ],\n \"createdTime\": \"2021-05-24T04:19:13.000Z\",\n \"fields\": {\n \"Name\": \"Vantage\",\n \"Style\": \"Cooperative\",\n \"Is Available?\": 0\n },\n \"id\": \"recKPmZ4DkjYyFrV4\"\n },\n```\n\n## Differences from Upstream\n\nThis was originally forked from [simonw/airtable-export](https://github.com/simonw/airtable-export) and has since diverged. In the interest of simplicity & my own needs, I:\n\n- made `backup_directory` optional; it defaults to `./airtable-backup-<ISO_DATE>`\n- removed `ndjson`, `yaml`, and `sqlite` options; it always outputs formatted JSON\n- removed `base_id`; it pulls every base the auth token has access to\n- removed `user-agent` option for simplicity (though would be open to re-adding it later, if needed). It makes calls as default of `backup-airtable`\n- removed `schema` option; it always dumps the schema\n- removed `http-read-timeout`; it defaults to a high-enough value of 60 seconds\n- it doesn't flatten the record. the top level keys are `id`, `createdTime`, and `fields`\n\n## Development\n\nThis project uses [just](https://github.com/casey/just) for running tasks. First, create a virtualenv:\n\n```shell\npython -m venv .venv\nsource .venv/bin/activate\n```\n\nThen run `just install` to install the project and its development dependencies. At that point, the `backup-airtable` will be available. Run `just` to see all the available commands.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Quickly and painlessly dump all your Airtable schemas & data to JSON.",
"version": "0.2.0",
"project_urls": {
"Author": "https://xavd.id",
"Bug Tracker": "https://github.com/xavdid/backup-airtable/issues",
"Changelog": "https://github.com/xavdid/backup-airtable/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/xavdid/backup-airtable"
},
"split_keywords": [
"airtable",
" backup",
" exporter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f7625ee8e2701942ff658f9d05eceff3a14f64f84e6a1864de182b0b24675e70",
"md5": "9f1ea3abefd607a411a39ade35023ee6",
"sha256": "63ea40e04bdbdda5b825c745a18e08889c8a3ebbce061a0e62b81c35a484f1c2"
},
"downloads": -1,
"filename": "backup_airtable-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f1ea3abefd607a411a39ade35023ee6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11446,
"upload_time": "2025-02-23T07:34:53",
"upload_time_iso_8601": "2025-02-23T07:34:53.161665Z",
"url": "https://files.pythonhosted.org/packages/f7/62/5ee8e2701942ff658f9d05eceff3a14f64f84e6a1864de182b0b24675e70/backup_airtable-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1fdf824ad11e89959762bb70e603406ce8f44bf6c3dfa1e66872910bcb65769",
"md5": "f09059b57974c47af131e3073e887d2d",
"sha256": "2bf3a3cbcc9da159546e450f9f5826d50d6433c0f2afc8e2346f19c584d97b8c"
},
"downloads": -1,
"filename": "backup_airtable-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f09059b57974c47af131e3073e887d2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10963,
"upload_time": "2025-02-23T07:34:54",
"upload_time_iso_8601": "2025-02-23T07:34:54.841293Z",
"url": "https://files.pythonhosted.org/packages/c1/fd/f824ad11e89959762bb70e603406ce8f44bf6c3dfa1e66872910bcb65769/backup_airtable-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 07:34:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xavdid",
"github_project": "backup-airtable",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "backup-airtable"
}
