Add info re: creating persistent db files

[dnlmc]

Adding some notes about creating new persistent db files. (following this discord convo)

Wasn't sure where was the best place for the info so added blurbs based on existing verbiage to:

• docs/data/overview.md
• docs/api/python.md
• docs/api/r.md
• docs/api/rust.md

Might also want to create a page or reference within guides/

[Mytherin]

Thanks for the changes! Looks good, minor comment:

[Mytherin]

As mentioned in the comment this feels out of place on the data import overview. A separate "Connect" page would make more sense (or perhaps just leave it out for now).

[dnlmc]

@Mytherin that makes sense. These updates were a result of me searching the documentation for confirmation on how to create persistent db files, & not finding anything. Maybe a "Connect & persist a database" section would make sense?

[Mytherin]

A Connect section would be fine, although the problem with that is that this is different for every single client. It could contain links to the pages of different clients, perhaps?

[dnlmc]

@Mytherin yea, I included updates in the Client APIs section for some specific clients where I could infer the proper approach (R, Python, Rust). Those are also part of this PR.

But wasn't sure where to put this generic instruction (which also refers & links to the API docs section for client-specific usage). And wasn't sure if it was worth its own whole page. There also seems to be some redundancy between the Guides & Documentation sections, so wasn't sure where is best:

As a new user, I was simply looking for info on creating & persisting database files, & could find no mentions in the docs. So my suggestion again would be something like an explicit Connect & persist a database section in either Guides or Documentation, but will defer to the team.

[Mytherin]

But wasn't sure where to put this generic instruction (which also refers & links to the API docs section for client-specific usage). And wasn't sure if it was worth its own whole page. There also seems to be some redundancy between the Guides & Documentation sections, so wasn't sure where is best:

The Guides are meant as quick guides to accomplish specific goals, whereas the documentation (which should perhaps be renamed to Reference) is meant as a comprehensive reference that describes all available options. The guides serve as a starting point that point to the documentation section.

As a new user, I was simply looking for info on creating & persisting database files, & could find no mentions in the docs. So my suggestion again would be something like an explicit Connect & persist a database section in either Guides or Documentation, but will defer to the team.

The problem is that there is no generic way of connecting to and persisting a database. How to do this depends on which client you are using. Perhaps for now it is better to just leave this bit out, and leave the information only in the specific client API sections.

[dnlmc]

@Mytherin Gotcha.

Would something like this work as a generic placeholder for folks like me specifically looking for this info?

Connect or Create a DB

To use DuckDB, you must first create a connection to a database. This process varies by client (see API docs for client-specific usage). Most Client APIs take a parameter pointing to a database file to read and write from (the file extension may be anything, e.g. .db, .duckdb, etc.). If the database file does not exist, it will be created. The special value :memory: can typically be used to create an in-memory database where no data is persisted to disk (i.e. all data is lost when you exit the process). Again, see API docs for client-specific details.

Otherwise I can just remove this generic info from the PR & only keep the added details in the Client APIs section.

[Mytherin]

Sounds good, perhaps only include the link once:

Connect or Create a DB

To use DuckDB, you must first create a connection to a database. The exact process varies by client. Most clients take a parameter pointing to a database file to read and write from (the file extension may be anything, e.g. .db, .duckdb, etc.). If the database file does not exist, it will be created. The special value :memory: can be used to create an in-memory database where no data is persisted to disk (i.e. all data is lost when you exit the process). See the API docs for client-specific details.

Could you then add a Connect page at the top of the Documentation that includes this?

[dnlmc]

I've got that change ready to commit!

Do I need to do anything other than add a connect.md file to the docs/ folder? (& undo the change to overview.md)

e.g. any changes to _data/menu_docs_* to add the page to the sidebar menu?

[Mytherin]

Yes, you need to change the menu_docs as well when creating a new page.

[dnlmc]

I have committed the changes:

• reverted overview.md changes
• added connect.md
• updated menu_docs_current.json (not 100% confident I did this right, so worth a check)

[Mytherin]

Thanks!

[dnlmc]

@Mytherin thanks for all your work on this project! love what you're doing here