backup-airtable


Namebackup-airtable JSON
Version 0.2.0 PyPI version JSON
download
home_pageNone
SummaryQuickly and painlessly dump all your Airtable schemas & data to JSON.
upload_time2025-02-23 07:34:54
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseNone
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"
}
        
Elapsed time: 0.46918s