45:["$","title",null,{"children":"Self-hosted database proxies | Observable | Observable"}] 4d:T4b7,viewof form = { const initial = { protocol: "postgresql", user: "visnup", password: "p@ssw0rd", host: "127.0.0.1", port: "5432", database: "testdb" }; const form = html` `; form.value = initial; form.addEventListener("input", (event) => { form.value[event.target.id] = event.target.value; }) return form; }4e:T5d1,tls = md`### SSL/TLS If you’re using Chrome or Edge and running the database proxy on your local computer (at 127.0.0.1), you can connect to it directly with HTTP — there’s no need to jump through the hoops of setting up a self-signed SSL certificate for the proxy, as the HTTP connection is entirely local to your computer. 💡 _We recommend using Chrome to connect to self-hosted database proxies running on 127.0.0.1._ To get them working with current versions of Firefox and Safari requires creating, installing and trusting a self-signed SSL certificate, which isn’t easy to set up. But if you still wish to use them with Firefox or Safari, here are the advanced instructions: 1. [Create and trust a self-signed SSL certificate](https://gist.github.com/cecilemuller/9492b848eb8fe46d462abeb26656c4f8) for the database proxy to use (or use a tool like [mkcert](https://github.com/FiloSottile/mkcert)). 2. Pass the \`--sslcert\` and \`--sslkey\` options, pointing to your newly created certificate, to the database proxy. When you’re creating the connection in Observable, make sure that the “Require SSL/TLS” option is selected. 3. Visit https://127.0.0.1:2899/ and click “Accept the risk” to allow Firefox to use your self-signed certificate. and configure the database proxy to use it in order to proxy over HTTPS. 4. Now you can use your database connector in Firefox or Safari.`4f:[{"id":"c02ee3b7ae5e550ae22b710d847db1e23756b55e8016407d2d82a8e974581ea264d1c65b507f2bef4bade1a4f52ad990f6008774a7203f1e1cb5c4467df3ca4a","href":"https://static.observableusercontent.com/files/c02ee3b7ae5e550ae22b710d847db1e23756b55e8016407d2d82a8e974581ea264d1c65b507f2bef4bade1a4f52ad990f6008774a7203f1e1cb5c4467df3ca4a","name":"image@1.png","type":"image/png","lastModified":1572544309735.486,"size":79479},{"id":"1f4d30260716207a5f2509c67882ad54958900c13e3b9e8e405c6a05a247496c88a769bbd079f634d15a9687d0d3bc00e4b32a96810ce01cfa4b3e3c62a313b1","href":"https://static.observableusercontent.com/files/1f4d30260716207a5f2509c67882ad54958900c13e3b9e8e405c6a05a247496c88a769bbd079f634d15a9687d0d3bc00e4b32a96810ce01cfa4b3e3c62a313b1","name":"image.png","type":"image/png","lastModified":1572544298954.753,"size":90187}] 49:{"id":"19c2395542095579","slug":"self-hosted-database-proxies","title":"Self-hosted database proxies","thumbnail":"115c3774240320ff6980268382ccb5b952be172dee34d7b741d0c93ccb980312","access_level":"public","create_time":"$D2019-07-02T00:03:18.640Z","update_time":"$D2023-09-06T16:14:40.338Z","view_time":null,"first_public_time":"$D2019-07-12T18:23:18.778Z","has_unpublished_edits":null,"fork":false,"stars":59,"starred":false,"owner":{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024","bio":"The computational, collaborative, agentic document where everyone answers questions with data","followed_by_you":false,"follows_you":false},"version":567,"publish_version":null,"role":null,"authored":false,"authors":[],"members":[{"type":"group","id":"c4990be612f2da51","login":"8788045797a2fd14","name":"Product Education","avatar_url":null,"tier":"public","role":"editor"},{"type":"individual","id":"074c414ad1d825f5","login":"mbostock","name":"Mike Bostock","avatar_url":"https://avatars-next.observableusercontent.com/7dbba99ced40bd5ab8013c99b1a11da61231bce321ba1148a9d16ad0f121550a","tier":null,"role":"editor"},{"type":"individual","id":"dbf69c13a14d2f62","login":"visnup","name":"Visnu Pitiyanuvath","avatar_url":"https://avatars-next.observableusercontent.com/b847c4c49993b1df7599d355f47dc0ad9c2dcf43439ce9e8f3410e6368b3aac9","tier":null,"role":"editor"},{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024","role":"viewer"}],"comments":[{"id":"03a8a1bf6a2ead1c","reply_to_id":null,"content":"mkcert (https://github.com/FiloSottile/mkcert) made the generation process a lot easier for me","create_time":"$D2022-06-30T01:20:50.689Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"16379e9551bd850d","login":"huw","name":"huw","avatar_url":"https://avatars-next.observableusercontent.com/d4b15139cfa29ef742c90b040fbd38621c517cac8270b3ec32211ee0669b0920","tier":null}},{"id":"91ce6ac439bfe2f1","reply_to_id":"03a8a1bf6a2ead1c","content":"Nice, I added a mention of it to the docs. Thanks!","create_time":"$D2022-08-24T19:19:21.851Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"dbf69c13a14d2f62","login":"visnup","name":"Visnu Pitiyanuvath","avatar_url":"https://avatars-next.observableusercontent.com/b847c4c49993b1df7599d355f47dc0ad9c2dcf43439ce9e8f3410e6368b3aac9","tier":null}}],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":39,"collection":{"id":"69718aa29ac11e6c","slug":"getting-data-in-and-out","title":"Getting Data In and Out","owner":{"id":"f35c755083683fe5","login":"observablehq","name":"Observable"}},"type":"notebook","body":{"titling":"auto","title":"Self-hosted database proxies","cells":[{"id":0,"value":"md`# Self-hosted database proxies\n\nObservable’s hosted [database clients](/@observablehq/connecting-to-databases) rely on an HTTPS-to-database proxy, which allows your browser to securely run SQL queries against databases that are accessible from the public internet.\n\nBut if your database isn’t accessible from the public internet (say, because you’re running it on your personal computer, or on a private network, or within a VPN) — or if you simply don’t wish to share any database credentials with Observable — that won’t work.\n\nSo we also provide a small, [open-source](https://github.com/observablehq/database-proxy) Node.js database proxy, [available on npm](https://www.npmjs.com/package/@observablehq/database-proxy) that you can run yourself. By connecting directly from your browser to the proxy, your private notebooks can access databases on private networks or local computers, that traffic never goes over the public internet, and you don’t need to trust Observable with any database credentials.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":454,"value":"## Setup","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":514,"value":"md`### Install \\`@observablehq/database-proxy\\` with npm or Yarn:\n\n${codeblock(`\nnpm install -g @observablehq/database-proxy \n`)}\n${codeblock(`\nyarn global add @observablehq/database-proxy\n`)}\n\nOn initial startup, the proxy will walk you through configuration.\n\n${codeblock(`\nobservable-database-proxy add testdb\n`)}\n\nObservablehq.com will open to your database settings page, and offer to configure a new self-hosted database proxy. \n`\n","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":517,"value":"

\n \n

Setting a proxy to a local PostgreSQL database

\n \n

Copying the shared secret

\n","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":449,"value":"credentials = md`### Credentials\n\nNext, tell the proxy about the database credentials you’d like to use locally to connect to your database, in the form of a PostgreSQL, MySQL, or Snowflake URL, for example:\n\n${codeblock(`\n postgresql://visnup@127.0.0.1/testdb\n`, '')}\nor\n${codeblock(`\n mysql://dbuser:dbpassword@127.0.0.1/testdb\n`, '')}\n\n*Note: If you’re proxying to a database over SSL, you can add it as a URL parameter. For example, for PostgreSQL, with \\`?sslmode=no-verify\\`, or for MySQL/MongoSQL with \\`sslMode=REQUIRED\\`.*\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":566,"value":"Be sure to encode special characters in any of the fields. To help with this, you can use the form below to construct a URL.\n\nCopy and paste this URL: ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":395,"value":"url = {\n const {protocol, user, password, host, port, database} = form;\n const url = `${protocol}://${encodeURIComponent(user)}${\n password.length ? ':' + encodeURIComponent(password) : ''}${\n user.length + password.length > 0 ? '@' : ''}${\n host}${\n port.length ? ':' + port : ''}${\n database.length ? '/' + encodeURIComponent(database) : ''}`;\n return md`${url}`;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":377,"value":"$4d","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":465,"value":"md`⚠️ _Be wary of any form on the internet prompting you for a password! Feel free to inspect this code to ensure nothing nefarious is happening. Or, use it as an example of using \\`encodeURIComponent\\` to encode special characters._`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":348,"value":"## Usage\n\nTo boot up the proxy:\n\n${codeblock(`\nobservable-database-proxy start testdb\n`)}\n\nHere’s the full list of commands:\n\n- \\`start <name> [ssl options]\\` *(Start a database proxy server)*\n- \\`add <name>\\` *(Add a new database proxy configuration)*\n- \\`remove <name>\\` *(Remove an existing database proxy configuration)*\n- \\`reset <name>\\` *(Reset the shared secret for an existing database proxy configuration)*\n- \\`list\\` *(List all configured database proxies)*","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":31,"value":"$4e","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":224,"value":"md`### Querying\nOnce your database proxy is up and running, you can create a database client connected to it by calling \\`DatabaseClient(\"name\")\\` in a private notebook.\n\n[For more information on querying with Database Clients, see the introductory notebook.](https://observablehq.com/d/a856f2a939b81d53)`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":189,"value":"md`### Configuration file\nYour database credentials and secret key for any configured local proxies are stored on your machine in \\`~/.observablehq\\`. If you restart the database proxy, it will read previous configuration from this file.\n\nIf you want to reset everything, delete this file.\n\nIf you want to remove just a single database proxy configuration, run:\n\n${codeblock(`\nobservable-database-proxy remove \n`)}\n\nIf desired, you can reset the shared secret for a local database proxy from your **Databases** settings page. With the new secret in hand, run: \n${codeblock(`\nobservable-database-proxy reset \n`)}\n\\u{200b}\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":538,"value":"md`### Using with Oracle\n\nUsing the self hosted database proxy with an Oracle database requires a few extra steps in the installation. Please refer to the [README](https://github.com/observablehq/database-proxy#installing-for-oracle-databases) for more information.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":532,"value":"---","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":366,"value":"viewof codeblock = {\n const css = html``\n css.value = (content, prefix = '$ ') =>\n html`\n

${prefix\n        ? content.trim().split('\\n').map(line => html`\n            ${DOM.text(line + '\\n')}\n          `)\n        : DOM.text(content.trim())}

\n `\n\n return css\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W4f","stdlib":"1"}} 44:null