> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# cockroach userfile get
export const InternalLink = ({version, path = "", children, ...props}) => {
let detectedVersion = version || "stable";
if (typeof window !== 'undefined' && !version) {
const match = window.location.pathname.match(/\/docs\/([^/]+)/);
if (match) {
detectedVersion = match[1];
}
}
const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
return
{children}
;
};
The `cockroach userfile get` command fetches the files stored in the user-scoped file storage which match the provided pattern, using a SQL connection. If no pattern is provided, all files in the specified (or default, if unspecified) user-scoped file storage will be fetched.
## Required privileges
The user must have `CONNECT` privileges on the target database.
A user can only fetch files from their own user-scoped storage, which is accessed through the userfile URI used during the upload. CockroachDB will revoke all access from every other user in the cluster except users in the `admin` role and users explicitly granted access.
If this is your first interaction with user-scoped file storage, you may see an error indicating that you need `CREATE` privileges on the database. You must first upload a file or run a `BACKUP` to `userfile` before attempting to `get` a file.
## Synopsis
Fetch a file:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile get [flags]
```
View help:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile get --help
```
## Flags
| Flag | Description | |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | `--cert-principal-map` | A comma-separated list of `:` mappings. This allows mapping the principal in a cert to a DB principal such as `node` or `root` or any SQL user. This is intended for use in situations where the certificate management system places restrictions on the `Subject.CommonName` or `SubjectAlternateName` fields in the certificate (e.g., disallowing a `CommonName` like `node` or `root`). If multiple mappings are provided for the same \`\`, the last one specified in the list takes precedence. A principal not specified in the map is passed through as-is via the identity function. A cert is allowed to authenticate a DB principal if the DB principal name is contained in the mapped `CommonName` or DNS-type `SubjectAlternateName` fields. |
| `--certs-dir` | The path to the certificate directory containing the CA and client certificates and client key. **Env Variable:**`COCKROACH\_CERTS\_DIR` **Default:**`${HOME}/.cockroach-certs/` | |
| `--echo-sql` | Reveal the SQL statements sent implicitly by the command-line utility. | |
| `--url` | A connection URL to use instead of the other arguments. **Env Variable:**`COCKROACH\_URL` **Default:** no URL | |
| `--user` `-u` | The SQL user that will own the client session. **Env Variable:**`COCKROACH\_USER` **Default:**`root` | |
## Examples
### Get a specific file
To get the file named test-data.csv from the default user-scoped storage location for the current user:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile get test-data.csv --certs-dir=certs
```
### Get a file saved to an explicit local file name
To get a file named test-data.csv from a local directory:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile get test-data.csv /Users/maxroach/Desktop/test-data.csv --certs-dir=certs
```
### Get a file from a non-default userfile URI
If you uploaded a file to a non-default userfile URI (e.g., `userfile://testdb.public.uploads`), use the same URI to fetch it:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach userfile get userfile://testdb.public.uploads/test-data.csv --certs-dir=certs
```
### Get files that match the provided pattern
To get all files that match a pattern, use \*:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile get '*.csv' --certs-dir=certs
```
## See also
* `cockroach userfile upload`
* `cockroach userfile delete`
* `cockroach userfile list`
* Use `userfile` storage
* `cockroach` Commands Overview