> ## Documentation Index > Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Use Userfile Storage To put files on your CockroachDB cluster without external servers, use `userfile`, a per-user file storage. To interact with `userfile`, use the following [commands](https://docs.cockroachlabs.com/docs/stable/cockroach-commands.md): * [`cockroach userfile upload`](#upload-a-file) * [`cockroach userfile list`](#list-files) * [`cockroach userfile get`](#get-files) * [`cockroach userfile delete`](#delete-files) Once a userfile is uploaded, you can run [`IMPORT INTO`](#import-from-userfile). You can create an external connection to represent an external storage or sink URI. This allows you to specify the external connection's name in statements rather than the provider-specific URI. For detail on using external connections, see the [`CREATE EXTERNAL CONNECTION`](https://docs.cockroachlabs.com/docs/stable/create-external-connection) page. ## Upload a file > [!NOTE] > > A userfile uses storage space in the cluster, and is replicated with the rest of the cluster's data. We recommend using [`cockroach userfile upload`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-upload) for quick uploads from your client (about 15MB or smaller). ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach userfile upload /Users/maxroach/Desktop/test-data.csv /test-data.csv --certs-dir=certs ``` ``` successfully uploaded to userfile://defaultdb.public.userfiles_root/test-data.csv ``` For more information, see [`cockroach userfile upload`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-upload). ## List files ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach userfile list '*.csv' --certs-dir=certs ``` ``` userfile://defaultdb.public.userfiles_root/test-data-2.csv userfile://defaultdb.public.userfiles_root/test-data.csv ``` For more information, see [`cockroach userfile list`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-list). ## Get files ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach userfile get test-data.csv --certs-dir=certs ``` For more information, see [`cockroach userfile get`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-get). ## Delete files ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach userfile delete test-data.csv --certs-dir=certs ``` ``` deleted userfile://defaultdb.public.userfiles_root/test-data.csv ``` For more information, see [`cockroach userfile delete`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-delete). ## Import from `userfile` To import from `userfile`, first create the table that you would like to import into: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} CREATE TABLE customers ( id INT, dob DATE, first_name STRING, last_name STRING, joined DATE ); ``` Then, use `IMPORT INTO` to import data into the table: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} IMPORT INTO customers (id, dob, first_name, last_name, joined) CSV DATA ('userfile:///test-data.csv'); ``` `userfile:///` references the default path (`userfile://defaultdb.public.userfiles_$user/`). ``` job_id | status | fraction_completed | rows | index_entries | bytes ---------------------+-----------+--------------------+--------+---------------+----------- 599865027685613569 | succeeded | 1 | 300024 | 0 | 13389972 (1 row) ``` For more import options, see [`IMPORT INTO`](https://docs.cockroachlabs.com/docs/stable/import-into). ## Backup and restore with `userfile` We recommend starting backups from a time at least 10 seconds in the past using [`AS OF SYSTEM TIME`](https://docs.cockroachlabs.com/docs/stable/as-of-system-time). Read our guidance in the [Performance](https://docs.cockroachlabs.com/docs/stable/backup.md#performance) section on the [`BACKUP`](https://docs.cockroachlabs.com/docs/stable/backup) page. > [!NOTE] > > Only database and table-level backups are possible when using `userfile` as storage. Restoring cluster-level backups will not work because `userfile` data is stored in the `defaultdb` database, and you cannot restore a cluster with existing table data. When working on the same cluster, `userfile` storage allows for database and table-level backups. First, run the following statement to backup a database to a directory in the default `userfile` space: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} BACKUP DATABASE bank INTO 'userfile://defaultdb.public.userfiles_$user/bank-backup' AS OF SYSTEM TIME '-10s'; ``` This directory will hold the files that make up a backup; including the manifest file and data files. > [!NOTE] > > When backing up from a cluster and restoring a database or table that is stored in your `userfile` space to a different cluster, you can run [`cockroach userfile get`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-get) to download the backup files to a local machine and [`cockroach userfile upload -r --url {CONNECTION STRING}`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-upload#upload-a-directory-recursively) to upload to the `userfile` of the restoring cluster. In cases when your database needs to be restored, run the following: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} RESTORE DATABASE bank FROM LATEST IN 'userfile://defaultdb.public.userfiles_$user/bank-backup'; ``` It is also possible to run `userfile:///bank-backup` as `userfile:///` refers to the default path `userfile://defaultdb.public.userfiles_$user/`. Once the backup data is no longer needed, delete from the `userfile` storage with the following command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach userfile delete bank-backup --url {CONNECTION STRING} ``` If you use `cockroach userfile delete {file}`, it will take as long as the [garbage collection](https://docs.cockroachlabs.com/docs/stable/configure-replication-zones.md#gc-ttlseconds) to be removed from disk. ## See also * [`cockroach userfile upload`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-upload) * [`cockroach userfile list`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-list) * [`cockroach userfile get`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-get) * [`cockroach userfile delete`](https://docs.cockroachlabs.com/docs/stable/cockroach-userfile-delete) * [`cockroach` Commands Overview](https://docs.cockroachlabs.com/docs/stable/cockroach-commands) * [`IMPORT INTO`](https://docs.cockroachlabs.com/docs/stable/import-into)