> ## 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 nodelocal upload

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 <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

The `cockroach nodelocal upload` <InternalLink path="cockroach-commands">command</InternalLink> 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>

<Note>
  CockroachDB now supports uploading files to a <InternalLink path="use-userfile-storage">user-scoped file storage</InternalLink> using a SQL connection. We recommend using `userfile` instead of `nodelocal`, as it is user-scoped and more secure.
</Note>

## 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 <InternalLink path="cockroach-start#general">`--external-io`</InternalLink> 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 <InternalLink path="cockroach-cert">certificate directory</InternalLink> containing the CA and client certificates and client key.<br /><br />**Env Variable:** `COCKROACH_CERTS_DIR`<br />**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. <br /><br />**Env Variable:** `COCKROACH_HOST`<br />**Default:** `localhost:26257`                                                               |
| `--insecure`       | Use an insecure connection.<br /><br />**Env Variable:** `COCKROACH_INSECURE`<br />**Default:** `false`                                                                                                                                             |
| `--url`            | A <InternalLink path="connection-parameters#connect-using-a-url">connection URL</InternalLink> to use instead of the other arguments.<br /><br />**Env Variable:** `COCKROACH_URL`<br />**Default:** no URL                                         |
| `--user`<br />`-u` | The <InternalLink path="create-user">SQL user</InternalLink> that will own the client session.<br /><br />**Env Variable:** `COCKROACH_USER`<br />**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 <InternalLink path="import">`IMPORT`</InternalLink> or <InternalLink path="import-into">`IMPORT INTO`</InternalLink> 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 <InternalLink path="import">`IMPORT`</InternalLink> or <InternalLink path="import-into">`IMPORT INTO`</InternalLink> data.

## See also

* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>
* <InternalLink path="troubleshooting-overview">Troubleshooting Overview</InternalLink>
* <InternalLink path="import">`IMPORT`</InternalLink>
* <InternalLink path="import-into">`IMPORT INTO`</InternalLink>