> ## 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.

# cockroach nodelocal upload

The `cockroach nodelocal upload` [command](/docs/stable/cockroach-commands.md) uploads a file to the external IO directory on a node's (the gateway node, by default) local file system.

This command takes in a source file to upload and a destination filename. It will then use a SQL connection to upload the file to the node's local file system, at `externalIODir/destination/filename`.

> [!NOTE]
>
> The source file is only uploaded to one node, not all of the nodes.

> [!NOTE]
>
> CockroachDB now supports uploading files to a [user-scoped file storage](/docs/stable/use-userfile-storage.md) using a SQL connection. We recommend using `userfile` instead of `nodelocal`, as it is user-scoped and more secure.

## Required privileges

Only members of the `admin` role can run `cockroach nodelocal upload`. By default, the `root` user belongs to the `admin` role.

## Considerations

The [`--external-io`](/docs/stable/cockroach-start#general) flag on the node you're uploading to **cannot** be set to `disabled`.

## Synopsis

Upload a file:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach nodelocal upload <location/of/file> <destination/of/file> [flags]
```

View help:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach nodelocal upload --help
```

## Flags

| Flag | Description |
| - | - |
| `--certs-dir` | The path to the [certificate directory](/docs/stable/cockroach-cert.md) 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. |
| `--host` | The server host and port number to connect to. This can be the address of any node in the cluster.  **Env Variable:** `COCKROACH_HOST` **Default:** `localhost:26257` |
| `--insecure` | Use an insecure connection. **Env Variable:** `COCKROACH_INSECURE` **Default:** `false` |
|  `--url` | A [connection URL](/docs/stable/connection-parameters.md#connect-using-a-url) to use instead of the other arguments. **Env Variable:** `COCKROACH_URL` **Default:** no URL |
| `--user` `-u` | The [SQL user](/docs/stable/create-user.md) that will own the client session. **Env Variable:** `COCKROACH_USER` **Default:** `root` |

## Examples

### Upload a file

To upload a file to the default node (i.e., the gateway node):

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach nodelocal upload ./grants.csv test/grants.csv --certs-dir=certs
```

```
successfully uploaded to nodelocal://1/test/grants.csv
```

Then, you can use the file to [`IMPORT INTO`](/docs/stable/import-into) data.

### Upload a file to a specific node

To upload a file to a specific node (e.g., node 2), use the `--host` flag:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach nodelocal upload ./grants.csv grants.csv --host=localhost:26259 --insecure
```

```
successfully uploaded to nodelocal://2/grants.csv
```

Or, use the `--url` flag:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach nodelocal upload ./grants.csv grants.csv --url=postgresql://root@localhost:26258?sslmode=disable --insecure
```

```
successfully uploaded to nodelocal://3/grants.csv
```

Then, you can use the file to [`IMPORT INTO`](/docs/stable/import-into) data.

## See also

* [`cockroach` Commands Overview](/docs/stable/cockroach-commands)
* [Troubleshooting Overview](/docs/stable/troubleshooting-overview.md)
* [`IMPORT INTO`](/docs/stable/import-into)